de-freelance-intake.md617 lines27.0 KB
v1Orchestrator
| 1 | --- |
| 2 | name: de-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their German tax returns AND mentions freelancing (Freiberufler), self-employment (Selbstständigkeit), trade business (Gewerbetreibender), contracting, or sole proprietorship (Einzelunternehmer). Trigger on phrases like "help me do my German taxes", "prepare my EStE", "I'm self-employed in Germany", "I'm a Freiberufler", "do my Steuererklärung", "prepare my USt and ESt", or any similar phrasing where the user is a Germany-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Germany self-employed tax workflow -- every other skill in the stack (germany-vat-return, de-income-tax, de-social-contributions, de-trade-tax, de-estimated-tax, de-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Germany full-year residents only; self-employed individuals and sole proprietors. |
| 4 | version: 0.1 |
| 5 | --- |
| 6 | |
| 7 | # Germany Self-Employed Intake Skill v0.1 |
| 8 | |
| 9 | ## What this file is |
| 10 | |
| 11 | The intake orchestrator for Germany-resident self-employed individuals (Freiberufler and Gewerbetreibende). Every downstream Germany content skill (germany-vat-return, de-income-tax, de-social-contributions, de-trade-tax, de-estimated-tax) and the assembly orchestrator (de-return-assembly) depend on this skill running first to produce a structured intake package. |
| 12 | |
| 13 | This skill does not compute any tax figures. Its job is to collect all the facts, parse all the documents, confirm everything with the user, and hand off a clean intake package to `de-return-assembly`. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Design principles |
| 18 | |
| 19 | v0.1 follows the same upload-first, inference-then-confirm pattern as mt-freelance-intake v0.1: |
| 20 | |
| 21 | 1. **Compact refusal sweep** using `ask_user_input_v0` -- 3-5 interactive questions, ~30 seconds. |
| 22 | 2. **Upload-first workflow** -- after the refusal check, the user dumps everything they have. |
| 23 | 3. **Inference pass** -- Claude parses every document and extracts as much as possible. |
| 24 | 4. **Gap-filling only** -- Claude asks the user ONLY about what is missing, ambiguous, or needs confirmation. |
| 25 | 5. **Single confirmation pass** at the end -- show the full picture, let the user correct anything wrong, hand off to downstream skills. |
| 26 | |
| 27 | Target: intake completes in 5 minutes for a prepared user, 15 minutes for a user who has to go fetch documents. |
| 28 | |
| 29 | ## Critical operating principles |
| 30 | |
| 31 | **Do not narrate the workflow.** Do not say "Phase 1," "Phase 2," "Now I'll ask you about deductions." Just do the work. |
| 32 | |
| 33 | **Do not ask questions that have already been answered.** If the refusal check established the user is Regelbesteuert, do not later ask about VAT status. Track what is known. |
| 34 | |
| 35 | **Do not ask about things visible in uploaded documents.** If the bank statement shows quarterly Vorauszahlungen to the Finanzamt, do not ask "did you pay estimated tax." Confirm what you see, do not re-ask. |
| 36 | |
| 37 | **Use `ask_user_input_v0` for any multiple-choice question.** Text input is only for genuinely open-ended data (names, addresses, specific amounts when they cannot be inferred). |
| 38 | |
| 39 | **Prefer batching.** Ask 3 related questions in a single message when they do not depend on each other's answers. |
| 40 | |
| 41 | **Be terse but complete.** No hedging, no "let me know if you have questions," no "I hope this helps." |
| 42 | |
| 43 | **Exception for blocking decisions.** If a single question determines whether the user is in-scope or out-of-scope, ask it standalone. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Section 1 -- The opening |
| 48 | |
| 49 | When triggered, respond with ONE message that: |
| 50 | |
| 51 | 1. One-line greeting (no paragraph of expectation-setting) |
| 52 | 2. One-line summary of the flow (scope check -> upload -> gaps -> handoff to return assembly) |
| 53 | 3. One-line reviewer reminder (must be reviewed by Steuerberater before filing) |
| 54 | 4. Launch the refusal sweep immediately using `ask_user_input_v0` |
| 55 | |
| 56 | **Example first message:** |
| 57 | |
| 58 | > Let's get your 2025 German returns ready. Quick scope check, then you upload your documents, then I fill in the gaps. Target time: 10 minutes. |
| 59 | > |
| 60 | > Reminder: everything I produce needs to be reviewed and signed off by a Steuerberater before you file anything with the Finanzamt. I'm not a substitute for professional review. |
| 61 | > |
| 62 | > Scope check: |
| 63 | |
| 64 | Then immediately call `ask_user_input_v0` with the refusal questions. |
| 65 | |
| 66 | **Do NOT:** |
| 67 | - Write a welcome paragraph |
| 68 | - Explain the phases |
| 69 | - Ask "are you ready to start" |
| 70 | - List what documents you will eventually need |
| 71 | - Give a disclaimer beyond the one reviewer line |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## Section 2 -- Refusal sweep (compact) |
| 76 | |
| 77 | Present the refusal sweep as a single `ask_user_input_v0` call with 3 questions, all single-select. |
| 78 | |
| 79 | **The 3 questions to ask first:** |
| 80 | |
| 81 | ``` |
| 82 | Q1: "Germany residency in 2025?" |
| 83 | Options: ["Full year (unbeschränkt steuerpflichtig)", "Part year", "Did not live in Germany"] |
| 84 | |
| 85 | Q2: "Business structure?" |
| 86 | Options: ["Freiberufler (§18 EStG -- liberal profession)", "Gewerbetreibender (§15 EStG -- trade/business)", "GbR / Partnership", "GmbH / UG / Kapitalgesellschaft", "Not sure"] |
| 87 | |
| 88 | Q3: "VAT status?" |
| 89 | Options: ["Regelbesteuerung (standard VAT -- charge and reclaim USt)", "Kleinunternehmer §19 UStG (no VAT charged, under EUR 22,000)", "Not sure"] |
| 90 | ``` |
| 91 | |
| 92 | **After the response, evaluate:** |
| 93 | |
| 94 | - **Q1 = Full year** -> continue |
| 95 | - **Q1 = Part year or did not live in Germany** -> stop. "I'm set up for full-year German residents (unbeschränkt steuerpflichtig) only. Part-year or non-residents have different rules around beschränkte Steuerpflicht. You need a Steuerberater who handles non-resident returns." |
| 96 | |
| 97 | - **Q2 = Freiberufler** -> continue. No Gewerbesteuer applies. |
| 98 | - **Q2 = Gewerbetreibender** -> continue with a flag: Gewerbesteuer applies, will need Hebesatz for the municipality. |
| 99 | - **Q2 = GbR / Partnership** -> stop. "Partnerships file a separate Feststellungserklärung with different rules for profit allocation. You need a Steuerberater familiar with partnership returns." |
| 100 | - **Q2 = GmbH / UG / Kapitalgesellschaft** -> stop. "I don't cover corporate returns. Kapitalgesellschaften file KStE and GewStE with separate rules. You need a Steuerberater." |
| 101 | - **Q2 = Not sure** -> ask one follow-up: "What is your main activity? Freiberufler covers professions like software development, consulting, writing, design, medicine, law, engineering (Katalogberufe under §18 EStG). Gewerbetreibender covers trade, retail, manufacturing, or anything not listed under §18. If your Finanzamt issued a Gewerbeschein, you're Gewerbetreibender." |
| 102 | |
| 103 | - **Q3 = Regelbesteuerung** -> continue. Standard UStVA monthly/quarterly. |
| 104 | - **Q3 = Kleinunternehmer** -> continue. No UStVA filing required (unless voluntarily opted in). Turnover must stay under EUR 22,000 prior year / EUR 50,000 current year. |
| 105 | - **Q3 = Not sure** -> ask one follow-up: "Do you charge 19% (or 7%) USt on your invoices? If yes, you're Regelbesteuert. If your invoices say 'Kleinunternehmer gemäß §19 UStG' or show no USt, you're Kleinunternehmer." |
| 106 | |
| 107 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 108 | |
| 109 | ``` |
| 110 | Q4: "Employees?" |
| 111 | Options: ["No employees", "1-5 employees", "More than 5 employees"] |
| 112 | |
| 113 | Q5: "Partnerships or joint ventures?" |
| 114 | Options: ["None -- I operate alone", "I'm a partner in a GbR or other partnership alongside this business", "Not sure"] |
| 115 | ``` |
| 116 | |
| 117 | **Evaluate Q4:** |
| 118 | - **No employees** -> continue |
| 119 | - **1-5 employees** -> continue with a flag: Lohnsteuer obligations exist but are out of scope for this workflow. Flag for Steuerberater review. |
| 120 | - **More than 5** -> stop. "I'm set up for sole operators and very small businesses. With more than 5 employees, the payroll and Lohnsteuer complexity requires a dedicated Steuerberater." |
| 121 | |
| 122 | **Evaluate Q5:** |
| 123 | - **None** -> continue |
| 124 | - **Partner in a GbR** -> continue with a flag: partnership income will appear in the Feststellungsbescheid and needs to be entered in Anlage S or Anlage G. Will address during gap-filling. |
| 125 | - **Not sure** -> ask one follow-up: "Do you share business income with another person or file a joint business return (Feststellungserklärung)? If not, you operate alone." |
| 126 | |
| 127 | **Total time:** ~45 seconds if the user taps through. |
| 128 | |
| 129 | --- |
| 130 | |
| 131 | ## Section 3 -- The dump |
| 132 | |
| 133 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 134 | |
| 135 | **Example:** |
| 136 | |
| 137 | > Scope is good. Now upload everything you have for 2025 -- drop it all in at once: |
| 138 | > |
| 139 | > - Business Kontoauszüge (bank statements) for all of 2025 (CSV or PDF) |
| 140 | > - Ausgangsrechnungen (sales invoices) issued in 2025 |
| 141 | > - Eingangsrechnungen (purchase invoices / receipts) for business expenses |
| 142 | > - Prior year Steuerbescheid (tax assessment notice from the Finanzamt) |
| 143 | > - Vorauszahlungsbescheide (estimated tax payment notices) |
| 144 | > - Prior UStVA filings for 2025 (if Regelbesteuert) |
| 145 | > - EÜR from prior year (Anlage EÜR) |
| 146 | > - Krankenversicherung (health insurance) annual statement (Beitragsbescheinigung) |
| 147 | > - Any Finanzamt correspondence |
| 148 | > - Capital asset purchase receipts (computers, equipment, vehicles) |
| 149 | > - Anything else tax-related you have |
| 150 | > |
| 151 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 152 | |
| 153 | Then wait. Do not ask any other questions while waiting. |
| 154 | |
| 155 | **If the user uploads a partial dump and says "that's what I have":** move to inference. Do not demand more. Request specific missing items during gap-filling. |
| 156 | |
| 157 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 158 | > Check these places: |
| 159 | > - Business bank: download 2025 statements as PDF or CSV |
| 160 | > - Email: search for "Rechnung", "Steuerbescheid", "Vorauszahlung", "Finanzamt", "Krankenkasse" |
| 161 | > - ELSTER portal (elster.de): download prior returns and Steuerbescheide |
| 162 | > - Your Steuerberater from last year, if you had one |
| 163 | > - Dropbox / Google Drive for saved invoices |
| 164 | > - Krankenkasse portal: download Beitragsbescheinigung |
| 165 | > |
| 166 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 167 | |
| 168 | --- |
| 169 | |
| 170 | ## Section 4 -- The inference pass |
| 171 | |
| 172 | When documents arrive, parse each one. For each document, extract: |
| 173 | |
| 174 | **Bank statement (Kontoauszüge):** |
| 175 | - Total deposits (candidate Betriebseinnahmen) |
| 176 | - Recurring inflows (client payments with names) |
| 177 | - Outflows to Finanzamt (Vorauszahlungen ESt/SolZ/KiSt with dates) |
| 178 | - Outflows to Finanzamt (USt-Vorauszahlungen with dates) |
| 179 | - Outflows to Krankenkasse GKV or PKV (health insurance premiums) |
| 180 | - Outflows to Rentenversicherung (if voluntary or Pflichtversichert via Künstlersozialkasse) |
| 181 | - Equipment purchases (potential Anlagevermögen) |
| 182 | - Transfers to personal account (Privatentnahmen) |
| 183 | - Office rent payments (Büromiete) |
| 184 | - SaaS / software subscriptions |
| 185 | - Professional memberships (IHK Beiträge, Berufsverband) |
| 186 | - Insurance payments (Berufshaftpflicht, Kfz) |
| 187 | - Telefon / Internet payments |
| 188 | - Kfz expenses (fuel, maintenance, leasing) |
| 189 | |
| 190 | **Sales invoices (Ausgangsrechnungen):** |
| 191 | - Client names and amounts (netto + USt) |
| 192 | - Whether USt was charged (Regelbesteuerung indicator) |
| 193 | - Whether invoices say "Kleinunternehmer §19 UStG" (Kleinunternehmer indicator) |
| 194 | - Total Umsatz reconciliation against bank deposits |
| 195 | - Any EU clients (innergemeinschaftliche Leistung -- reverse charge) |
| 196 | - Any non-EU clients (Drittlandsleistung -- §3a UStG) |
| 197 | - Proper invoice format check (§14 UStG requirements) |
| 198 | |
| 199 | **Purchase invoices (Eingangsrechnungen):** |
| 200 | - Expense category (Betriebsausgaben, Anlagevermögen, durchlaufende Posten) |
| 201 | - Vorsteuer amount on each (reclaimable for Regelbesteuert, cost for Kleinunternehmer) |
| 202 | - Supplier location (inland, EU, Drittland) |
| 203 | - Any items over EUR 800 netto (GWG threshold for immediate write-off) or over EUR 250 (Pool-Abschreibung) |
| 204 | - Any blocked categories (Bewirtungskosten 70% limit, Geschenke EUR 50 limit) |
| 205 | |
| 206 | **Prior year Steuerbescheid:** |
| 207 | - Prior year festgesetzte Einkommensteuer (drives Vorauszahlungen) |
| 208 | - Prior year Solidaritätszuschlag |
| 209 | - Prior year Kirchensteuer (if applicable) |
| 210 | - Any Nachzahlung or Erstattung |
| 211 | - Vorauszahlungen festgesetzt for current year |
| 212 | |
| 213 | **Vorauszahlungsbescheide:** |
| 214 | - Quarterly ESt Vorauszahlungen (10 Mar, 10 Jun, 10 Sep, 10 Dec) |
| 215 | - SolZ amounts |
| 216 | - KiSt amounts (if applicable) |
| 217 | |
| 218 | **Prior EÜR (Anlage EÜR):** |
| 219 | - Prior year Betriebseinnahmen and Betriebsausgaben |
| 220 | - Prior year Gewinn |
| 221 | - Capital allowances schedule (AfA-Tabelle -- continuing depreciation) |
| 222 | - Any Sonderabschreibung §7g used |
| 223 | |
| 224 | **Krankenversicherung Beitragsbescheinigung:** |
| 225 | - Annual GKV or PKV premiums paid |
| 226 | - Basisabsicherung amount (deductible under §10 EStG as Sonderausgaben) |
| 227 | - Pflegeversicherung amount |
| 228 | - Any Zusatzbeiträge |
| 229 | |
| 230 | **After parsing everything, build an internal inference object.** Do not show the raw inference yet -- transform it into a compact summary for the user in Section 5. |
| 231 | |
| 232 | --- |
| 233 | |
| 234 | ## Section 5 -- The confirmation |
| 235 | |
| 236 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 237 | |
| 238 | **Example summary message:** |
| 239 | |
| 240 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 241 | > |
| 242 | > **Identity** |
| 243 | > - Max Mustermann, single |
| 244 | > - Full-year Germany resident (Berlin) |
| 245 | > - Freiberufler (Software-Entwickler), sole proprietor |
| 246 | > - VAT: Regelbesteuerung (USt-IdNr. DE123456789) |
| 247 | > |
| 248 | > **Umsatz (from bank statement + invoices)** |
| 249 | > - Betriebseinnahmen (netto): ~EUR 85,000 |
| 250 | > - TechCorp GmbH: EUR 48,000 (monthly retainer) |
| 251 | > - StartupAG: EUR 25,000 (project work) |
| 252 | > - Various smaller clients: EUR 12,000 |
| 253 | > - USt collected (19%): ~EUR 16,150 |
| 254 | > - EU reverse charge clients: EUR 8,000 (innergemeinschaftliche Leistung) |
| 255 | > |
| 256 | > **Betriebsausgaben (from bank statement + purchase invoices)** |
| 257 | > - Büromiete: EUR 6,000 |
| 258 | > - Software / SaaS: EUR 2,400 |
| 259 | > - Berufshaftpflicht: EUR 600 |
| 260 | > - Steuerberater Vorjahr: EUR 1,200 |
| 261 | > - Telefon / Internet: EUR 960 (TBD -- need business use %) |
| 262 | > - Kfz: EUR 3,600 fuel + EUR 800 maintenance (TBD -- need business use % or Fahrtenbuch) |
| 263 | > - MacBook Pro EUR 2,200 netto (April 2025) -- GWG? No, over EUR 800 -> AfA 3 years |
| 264 | > - Vorsteuer auf Eingangsrechnungen: ~EUR 2,300 (reclaimable) |
| 265 | > |
| 266 | > **Sozialversicherung (from Beitragsbescheinigung / bank statement)** |
| 267 | > - GKV (TK): EUR 8,400/year (Basisabsicherung EUR 7,200 + Zusatzbeitrag EUR 1,200) |
| 268 | > - Pflegeversicherung: EUR 1,800/year |
| 269 | > - Rentenversicherung: not detected (freiwillig?) |
| 270 | > |
| 271 | > **Vorauszahlungen (from Vorauszahlungsbescheid / bank statement)** |
| 272 | > - ESt Vorauszahlungen: EUR 2,500 x 4 = EUR 10,000 |
| 273 | > - SolZ: EUR 0 (under Freigrenze) |
| 274 | > - KiSt: not detected |
| 275 | > |
| 276 | > **Prior year (from 2024 Steuerbescheid)** |
| 277 | > - 2024 festgesetzte ESt: EUR 12,000 |
| 278 | > - 2024 Gewinn aus selbständiger Arbeit: EUR 42,000 |
| 279 | > - 2024 AfA-Tabelle: EUR 733 continuing depreciation |
| 280 | > |
| 281 | > **USt (from prior UStVA filings)** |
| 282 | > - Jan-Nov 2025 UStVA filed |
| 283 | > - December UStVA outstanding |
| 284 | > - Dauerfristverlängerung: yes (1/11 Sondervorauszahlung paid) |
| 285 | > |
| 286 | > **Flags I already see:** |
| 287 | > 1. Telefon / Internet -- need business use percentage |
| 288 | > 2. Kfz -- need business use percentage or Fahrtenbuch (1%-Regelung vs Fahrtenbuch) |
| 289 | > 3. MacBook Pro EUR 2,200 netto -- over GWG EUR 800, AfA über 3 Jahre (Nutzungsdauer lt. AfA-Tabelle) |
| 290 | > 4. December 2025 UStVA not yet filed -- will prepare as part of this workflow |
| 291 | > 5. No Rentenversicherung detected -- voluntary contributions? |
| 292 | > 6. Kirchensteuer status unclear |
| 293 | > |
| 294 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 295 | |
| 296 | --- |
| 297 | |
| 298 | ## Section 6 -- Gap filling |
| 299 | |
| 300 | After the user confirms the summary (or corrects it), ask about things that cannot be inferred from documents. Use `ask_user_input_v0` where possible. |
| 301 | |
| 302 | **Things that usually cannot be inferred:** |
| 303 | |
| 304 | 1. **Arbeitszimmer (home office)** -- Cannot tell from documents whether a dedicated Arbeitszimmer exists. Since 2023 reform: Tagespauschale (EUR 6/day, max EUR 1,260/year) or actual costs if Mittelpunkt der Tätigkeit. |
| 305 | 2. **Private use percentage** -- Telefon, Internet, Kfz business-use split. |
| 306 | 3. **Kfz method** -- 1%-Regelung vs Fahrtenbuch. |
| 307 | 4. **Capital allowances from prior years** -- Continuing AfA on assets acquired before 2025 (unless prior EÜR has the schedule). |
| 308 | 5. **GKV or PKV** -- Whether gesetzlich or privat krankenversichert (affects Sonderausgaben computation). |
| 309 | 6. **Kirchensteuer** -- Whether the user pays KiSt (8% or 9% depending on Bundesland). |
| 310 | 7. **Bundesland** -- Needed for Kirchensteuersatz and Gewerbesteuer Hebesatz (if Gewerbetreibender). |
| 311 | 8. **Other income** -- Employment income (Anlage N), rental (Anlage V), Kapitalerträge (Anlage KAP). |
| 312 | |
| 313 | **Home office gap-filling example:** |
| 314 | |
| 315 | Call `ask_user_input_v0` with: |
| 316 | |
| 317 | ``` |
| 318 | Q: "Arbeitszimmer (home office)?" |
| 319 | Options: [ |
| 320 | "Dedicated room at home, Mittelpunkt der gesamten Tätigkeit (I work there exclusively)", |
| 321 | "Dedicated room at home, but I also work at client sites", |
| 322 | "No dedicated room -- I use Tagespauschale (EUR 6/day, max EUR 1,260/year)", |
| 323 | "Separate business premises (Büromiete already captured)", |
| 324 | "No home office claim" |
| 325 | ] |
| 326 | ``` |
| 327 | |
| 328 | If option 1 -> actual cost method available. Ask for room size as % of total Wohnfläche, plus Miete/Nebenkosten amounts. |
| 329 | If option 2 -> Tagespauschale only (since 2023 reform, limited deduction unless Mittelpunkt). Flag as T2. |
| 330 | If option 3 -> ask for number of home office days in 2025. Compute EUR 6 x days, max EUR 1,260. |
| 331 | If option 4 -> rent already in Betriebsausgaben. Skip. |
| 332 | If option 5 -> skip entirely. |
| 333 | |
| 334 | **Kfz method example:** |
| 335 | |
| 336 | Call `ask_user_input_v0` with: |
| 337 | |
| 338 | ``` |
| 339 | Q: "Kfz -- business use method?" |
| 340 | Options: [ |
| 341 | "Fahrtenbuch (mileage log maintained all year)", |
| 342 | "1%-Regelung (Bruttolistenpreis method)", |
| 343 | "Km-Pauschale only (EUR 0.30/km for business trips, no car in Betriebsvermögen)", |
| 344 | "No vehicle used for business" |
| 345 | ] |
| 346 | ``` |
| 347 | |
| 348 | If Fahrtenbuch -> ask for total km, business km, and vehicle costs. Compute business %. |
| 349 | If 1%-Regelung -> ask for Bruttolistenpreis. Compute 1% x 12 months private use addition. |
| 350 | If Km-Pauschale -> ask for business km driven. EUR 0.30/km (EUR 0.38/km above 21st km for Pendlerpauschale, but that's for commuting, not business trips). |
| 351 | If no vehicle -> skip. |
| 352 | |
| 353 | **Kirchensteuer:** |
| 354 | |
| 355 | Call `ask_user_input_v0` with: |
| 356 | |
| 357 | ``` |
| 358 | Q: "Kirchensteuer?" |
| 359 | Options: [ |
| 360 | "Yes -- evangelisch or katholisch (church tax applies)", |
| 361 | "No -- no church membership (ausgetreten or never joined)" |
| 362 | ] |
| 363 | ``` |
| 364 | |
| 365 | If yes -> need Bundesland for rate (8% in Bayern/Baden-Württemberg, 9% elsewhere). |
| 366 | |
| 367 | **Bundesland:** |
| 368 | |
| 369 | Call `ask_user_input_v0` with: |
| 370 | |
| 371 | ``` |
| 372 | Q: "Bundesland?" |
| 373 | Options: [ |
| 374 | "Baden-Württemberg", "Bayern", "Berlin", "Brandenburg", "Bremen", |
| 375 | "Hamburg", "Hessen", "Mecklenburg-Vorpommern", "Niedersachsen", |
| 376 | "Nordrhein-Westfalen", "Rheinland-Pfalz", "Saarland", "Sachsen", |
| 377 | "Sachsen-Anhalt", "Schleswig-Holstein", "Thüringen" |
| 378 | ] |
| 379 | ``` |
| 380 | |
| 381 | Needed for: Kirchensteuersatz and Gewerbesteuer Hebesatz (if Gewerbetreibender -- will look up municipality Hebesatz during assembly). |
| 382 | |
| 383 | Flag all private-use percentages as T2 -- Steuerberater must confirm the percentage is reasonable and documented. |
| 384 | |
| 385 | --- |
| 386 | |
| 387 | ## Section 7 -- The final handoff |
| 388 | |
| 389 | Once gap-filling is done, produce a final handoff message and hand off to `de-return-assembly`. |
| 390 | |
| 391 | **Example handoff message:** |
| 392 | |
| 393 | > Intake complete. Here's what's going to the return assembly: |
| 394 | > |
| 395 | > Freiberufler, single, Regelbesteuerung, full-year Germany resident (Berlin). Betriebseinnahmen EUR 85,000, estimated Gewinn ~EUR 68,000 before Sonderausgaben and außergewöhnliche Belastungen. |
| 396 | > |
| 397 | > I'm now going to run the full German return preparation. This covers: |
| 398 | > 1. UStVA (December 2025 and Umsatzsteuererklärung) |
| 399 | > 2. ESt + EÜR (Einkommensteuererklärung with Anlage EÜR, Anlage S/G, Anlage Vorsorgeaufwand) |
| 400 | > 3. Sozialversicherungsbeiträge reconciliation (KV/PV/RV) |
| 401 | > 4. Gewerbesteuer (if Gewerbetreibender) |
| 402 | > 5. Vorauszahlungen schedule for 2026 |
| 403 | > |
| 404 | > You'll get back: |
| 405 | > 1. An Excel working paper with all forms and live formulas |
| 406 | > 2. A reviewer brief with positions, citations, and flags for your Steuerberater |
| 407 | > 3. A filing calendar with all upcoming deadlines |
| 408 | > |
| 409 | > Starting now. |
| 410 | |
| 411 | Then internally invoke `de-return-assembly` with the structured intake package. |
| 412 | |
| 413 | --- |
| 414 | |
| 415 | ## Section 8 -- Structured intake package (internal format) |
| 416 | |
| 417 | The downstream skill (`de-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 418 | |
| 419 | ```json |
| 420 | { |
| 421 | "jurisdiction": "DE", |
| 422 | "tax_year": 2025, |
| 423 | "taxpayer": { |
| 424 | "name": "", |
| 425 | "birth_year": 0, |
| 426 | "marital_status": "single | married | single_parent", |
| 427 | "residency": "full_year", |
| 428 | "bundesland": "", |
| 429 | "municipality": "", |
| 430 | "steuernummer": "", |
| 431 | "ust_id_nr": "", |
| 432 | "vat_status": "regelbesteuerung | kleinunternehmer", |
| 433 | "business_type": "freiberufler | gewerbetreibender", |
| 434 | "industry": "", |
| 435 | "entity_type": "sole_proprietor", |
| 436 | "kirchensteuer": true, |
| 437 | "kirchensteuer_rate": 0.08 |
| 438 | }, |
| 439 | "income": { |
| 440 | "betriebseinnahmen_netto": 0, |
| 441 | "ust_collected": 0, |
| 442 | "eu_reverse_charge_income": 0, |
| 443 | "drittland_income": 0, |
| 444 | "other_income": 0, |
| 445 | "client_breakdown": [] |
| 446 | }, |
| 447 | "expenses": { |
| 448 | "fully_deductible": [], |
| 449 | "mixed_use": [], |
| 450 | "limited_deduction": [], |
| 451 | "capital_items": [], |
| 452 | "gkv_pkv": { |
| 453 | "type": "GKV | PKV", |
| 454 | "annual_premium": 0, |
| 455 | "basisabsicherung": 0, |
| 456 | "pflegeversicherung": 0 |
| 457 | } |
| 458 | }, |
| 459 | "vat": { |
| 460 | "ustva_filed": [], |
| 461 | "dauerfristverlaengerung": false, |
| 462 | "sondervorauszahlung": 0, |
| 463 | "vorsteuer_reclaimable": 0, |
| 464 | "exempt_supplies": false |
| 465 | }, |
| 466 | "sozialversicherung": { |
| 467 | "gkv_or_pkv": "GKV | PKV", |
| 468 | "annual_kv_premium": 0, |
| 469 | "annual_pv_premium": 0, |
| 470 | "rentenversicherung": { |
| 471 | "type": "none | freiwillig | pflicht_ksk", |
| 472 | "annual_amount": 0 |
| 473 | } |
| 474 | }, |
| 475 | "vorauszahlungen": { |
| 476 | "est_quarterly": [], |
| 477 | "solz_quarterly": [], |
| 478 | "kist_quarterly": [], |
| 479 | "total_est_paid": 0, |
| 480 | "total_solz_paid": 0, |
| 481 | "total_kist_paid": 0 |
| 482 | }, |
| 483 | "prior_year": { |
| 484 | "festgesetzte_est": 0, |
| 485 | "festgesetzter_solz": 0, |
| 486 | "festgesetzte_kist": 0, |
| 487 | "gewinn": 0, |
| 488 | "afa_schedule": [] |
| 489 | }, |
| 490 | "home_office": { |
| 491 | "type": "mittelpunkt | tagespauschale | none", |
| 492 | "days_worked_at_home": 0, |
| 493 | "room_percentage": 0, |
| 494 | "annual_amount": 0 |
| 495 | }, |
| 496 | "private_use": { |
| 497 | "kfz_method": "fahrtenbuch | 1pct_regelung | km_pauschale | none", |
| 498 | "kfz_business_pct": 0, |
| 499 | "kfz_bruttolistenpreis": 0, |
| 500 | "telefon_business_pct": 0, |
| 501 | "internet_business_pct": 0 |
| 502 | }, |
| 503 | "gewerbesteuer": { |
| 504 | "applies": false, |
| 505 | "hebesatz": 0, |
| 506 | "municipality": "" |
| 507 | }, |
| 508 | "open_flags": [], |
| 509 | "refusals_triggered": [], |
| 510 | "documents_received": [] |
| 511 | } |
| 512 | ``` |
| 513 | |
| 514 | --- |
| 515 | |
| 516 | ## Section 9 -- Refusal handling |
| 517 | |
| 518 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., GmbH structure discovered in documents). |
| 519 | |
| 520 | When a refusal fires: |
| 521 | 1. Stop the workflow |
| 522 | 2. State the specific reason in one sentence |
| 523 | 3. Recommend the path forward (specific practitioner type) |
| 524 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 525 | |
| 526 | **Do not:** |
| 527 | - Apologize profusely |
| 528 | - Try to work around the refusal |
| 529 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 530 | - Continue silently |
| 531 | |
| 532 | **Sample refusal:** |
| 533 | |
| 534 | > Stop -- you have a registered GmbH. I'm set up for Freiberufler and Gewerbetreibende (Einzelunternehmer) only. GmbHs file Körperschaftsteuererklärung and Gewerbesteuererklärung with separate rules for Geschäftsführergehalt and Gewinnausschüttungen. You need a Steuerberater familiar with Kapitalgesellschaften. |
| 535 | > |
| 536 | > I can't help with this one. |
| 537 | |
| 538 | --- |
| 539 | |
| 540 | ## Section 10 -- Self-checks |
| 541 | |
| 542 | **Check IN1 -- No one-question-at-a-time prose in the refusal sweep.** If the skill asked "Question 1 of 10" or walked through questions as separate messages, check fails. |
| 543 | |
| 544 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 545 | |
| 546 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 547 | |
| 548 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 549 | |
| 550 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you pay Krankenversicherung" after the bank statement showed TK payments, check fails. |
| 551 | |
| 552 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 553 | |
| 554 | **Check IN7 -- Handoff to `de-return-assembly` is explicit.** The user was told "I'm now going to run the return preparation," and the downstream orchestrator was explicitly invoked with the intake package. |
| 555 | |
| 556 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned Steuerberater signoff. |
| 557 | |
| 558 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 559 | |
| 560 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 561 | |
| 562 | **Check IN11 -- Total user-facing turn count is low.** Target: 8 turns or fewer from start to handoff for a prepared user (1 refusal batch + 1 upload + 1 confirmation + 1-3 gap fills + 1 handoff). More than 12 turns for a normal intake is a check failure. |
| 563 | |
| 564 | **Check IN12 -- VAT status was established.** Regelbesteuerung vs Kleinunternehmer was confirmed before inference, as it changes how every transaction is classified. |
| 565 | |
| 566 | **Check IN13 -- Business type was established.** Freiberufler vs Gewerbetreibender was confirmed, as it determines Gewerbesteuer applicability. |
| 567 | |
| 568 | --- |
| 569 | |
| 570 | ## Section 11 -- Performance targets |
| 571 | |
| 572 | For a prepared user (documents in a folder, ready to upload): |
| 573 | - **Refusal sweep**: 45 seconds (1-2 interactive turns) |
| 574 | - **Document upload**: 2 minutes (1 upload turn) |
| 575 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 576 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 577 | - **Handoff**: immediate |
| 578 | - **Total**: ~6 minutes |
| 579 | |
| 580 | For an unprepared user (has to go fetch documents): |
| 581 | - Refusal sweep: same |
| 582 | - Document discovery: 10-20 minutes offline |
| 583 | - Rest: same |
| 584 | - **Total**: 15-25 minutes |
| 585 | |
| 586 | --- |
| 587 | |
| 588 | ## Section 12 -- Cross-skill references |
| 589 | |
| 590 | **Inputs:** User-provided documents and answers. |
| 591 | |
| 592 | **Outputs:** Structured intake package consumed by `de-return-assembly`. |
| 593 | |
| 594 | **Downstream skills triggered (via de-return-assembly):** |
| 595 | - `germany-vat-return` -- UStVA / Umsatzsteuererklärung |
| 596 | - `de-income-tax` -- ESt + EÜR (Einkommensteuererklärung with Anlage EÜR) |
| 597 | - `de-social-contributions` -- Krankenversicherung / Pflegeversicherung / Rentenversicherung |
| 598 | - `de-trade-tax` -- Gewerbesteuer (only if Gewerbetreibender) |
| 599 | - `de-estimated-tax` -- Vorauszahlungen schedule |
| 600 | |
| 601 | --- |
| 602 | |
| 603 | ### Change log |
| 604 | |
| 605 | - **v0.1 (April 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 606 | |
| 607 | ## End of Intake Skill v0.1 |
| 608 | |
| 609 | |
| 610 | --- |
| 611 | |
| 612 | ## Disclaimer |
| 613 | |
| 614 | This skill and its outputs are provided for informational and computational purposes only and do not constitute tax, legal, or financial advice. Open Accountants and its contributors accept no liability for any errors, omissions, or outcomes arising from the use of this skill. All outputs must be reviewed and signed off by a qualified professional (such as a Steuerberater, Wirtschaftsprüfer, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 615 | |
| 616 | The most up-to-date, verified version of this skill is maintained at [openaccountants.com](https://openaccountants.com). Log in to access the latest version, request a professional review from a licensed accountant, and track updates as tax law changes. |
| 617 |
Run this skill, then get an accountant to check it
After running the full skill pack in Claude, sign up and upload your worksheet. We'll connect you with a trusted accountant in our network who can review your numbers before you file.
Depends on
Quality
Q2: Research-verified
Deep research against tax authority sources. Not yet tested on real data.
Needs real client data + practitioner sign-off to reach Q1.
Accountant Review
Unverified
0/19
About
ALWAYS USE THIS SKILL when a user asks for help preparing their German tax returns AND mentions freelancing (Freiberufler), self-employment (Selbstständigkeit), trade business (Gewerbetreibender), contracting, or sole proprietorship (Einzelunternehmer). Trigger on phrases like "help me do my German taxes", "prepare my EStE", "I'm self-employed in Germany", "I'm a Freiberufler", "do my Steuererklärung", "prepare my USt and ESt", or any similar phrasing where the user is a Germany-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Germany self-employed tax workflow -- every other skill in the stack (germany-vat-return, de-income-tax, de-social-contributions, de-trade-tax, de-estimated-tax, de-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Germany full-year residents only; self-employed individuals and sole proprietors.
DEty-2025