es-freelance-intake.md594 lines25.9 KB
v1Orchestrator
| 1 | --- |
| 2 | name: es-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their Spain tax returns AND mentions freelancing, self-employment, autónomo, working por cuenta propia, or independent professional activity. Trigger on phrases like "help me do my taxes", "prepare my Modelo 100", "I'm autónomo in Spain", "I'm a freelancer in Spain", "do my taxes as an autónomo", "prepare my IRPF return", or any similar phrasing where the user is a Spain-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Spain self-employed tax workflow -- every other skill in the stack (spain-vat-return, es-income-tax, es-social-contributions, es-estimated-tax, es-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. Spain full-year residents only; autónomos (self-employed individuals) only. |
| 4 | version: 0.1 |
| 5 | --- |
| 6 | |
| 7 | # Spain Self-Employed Intake Skill v0.1 |
| 8 | |
| 9 | ## What this file is |
| 10 | |
| 11 | The intake orchestrator for Spain-resident self-employed individuals (autónomos). Every downstream Spain content skill (spain-vat-return, es-income-tax, es-social-contributions, es-estimated-tax) and the assembly orchestrator (es-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 `es-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 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 on estimación directa, do not later ask about the tax determination method. Track what is known. |
| 34 | |
| 35 | **Do not ask about things visible in uploaded documents.** If the RETA recibos show monthly contributions, do not ask "did you pay RETA." 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 qualified asesor fiscal 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 Spain 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 qualified asesor fiscal or gestor before you file anything with the AEAT. 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: "Spanish residency in 2025?" |
| 83 | Options: ["Full year (183+ days in Spain)", "Part year", "Did not live in Spain"] |
| 84 | |
| 85 | Q2: "Business structure?" |
| 86 | Options: ["Autónomo (persona física, trabajador por cuenta propia)", "Sociedad Limitada (SL)", "Sociedad Anónima (SA)", "Comunidad de bienes / Sociedad civil", "Not sure"] |
| 87 | |
| 88 | Q3: "Alta en RETA (registered with Social Security as self-employed)?" |
| 89 | Options: ["Yes, alta en RETA for all of 2025", "Yes, but only part of 2025", "No, not registered in RETA", "Not sure"] |
| 90 | ``` |
| 91 | |
| 92 | **After the response, evaluate:** |
| 93 | |
| 94 | - **Q1 = Full year** -> continue |
| 95 | - **Q1 = Part year** -> stop. "I'm set up for full-year Spanish residents only. Part-year residents have different rules around imputación temporal and may need to file in two jurisdictions. You need an asesor fiscal who handles non-resident or part-year returns." |
| 96 | - **Q1 = Did not live in Spain** -> stop. "I'm set up for Spanish tax residents only. Non-residents file Modelo 210 with different rules. You need an asesor fiscal who handles non-resident returns." |
| 97 | |
| 98 | - **Q2 = Autónomo** -> continue |
| 99 | - **Q2 = SL** -> stop. "I don't cover corporate returns. Sociedades Limitadas file Impuesto sobre Sociedades (Modelo 200) with separate rules. You need an asesor fiscal familiar with corporate tax." |
| 100 | - **Q2 = SA** -> stop. "I don't cover corporate returns. Sociedades Anónimas file Impuesto sobre Sociedades with separate rules. You need an asesor fiscal." |
| 101 | - **Q2 = Comunidad de bienes** -> stop. "Comunidades de bienes and sociedades civiles have specific attribution-of-income rules (Modelo 184). You need an asesor fiscal familiar with this structure." |
| 102 | - **Q2 = Not sure** -> ask one follow-up: "Do you invoice clients in your own name using your NIF (DNI/NIE)? Or do you have a registered company (SL/SA) with a CIF? If you invoice in your own name, you're an autónomo." |
| 103 | |
| 104 | - **Q3 = Yes, full year** -> continue |
| 105 | - **Q3 = Part year** -> continue with flag: RETA cuotas only deductible for months of alta. Prorate. |
| 106 | - **Q3 = Not registered** -> stop. "If you are performing economic activity without alta en RETA, that is a compliance issue that needs to be resolved first. Consult a gestor or laboralista." |
| 107 | - **Q3 = Not sure** -> ask one follow-up: "Do you pay a monthly cuota to the Seguridad Social (typically debited from your bank)? If yes, you're alta en RETA." |
| 108 | |
| 109 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 110 | |
| 111 | ``` |
| 112 | Q4: "Estimación directa type?" |
| 113 | Options: ["Estimación directa simplificada (default for most autónomos)", "Estimación directa normal", "Estimación objetiva (módulos)", "Not sure"] |
| 114 | |
| 115 | Q5: "Comunidad autónoma (where you have your fiscal domicile)?" |
| 116 | Options: ["Madrid", "Cataluña", "Andalucía", "Valencia", "País Vasco / Navarra (foral regime)", "Other (I'll specify)"] |
| 117 | |
| 118 | Q6: "How long have you been autónomo?" |
| 119 | Options: ["First year (2025)", "Second year", "Third year", "More than 3 years"] |
| 120 | ``` |
| 121 | |
| 122 | **Evaluate Q4:** |
| 123 | - **Simplificada** -> continue. Standard method for most autónomos. 5% gastos de difícil justificación (max EUR 2,000). |
| 124 | - **Normal** -> continue. Full accounting required, no simplified expense allowance. |
| 125 | - **Objetiva (módulos)** -> stop. "I'm set up for estimación directa only. Módulos uses a different calculation method based on physical parameters (surface, employees, kW). You need a gestor familiar with estimación objetiva." |
| 126 | - **Not sure** -> "If your turnover is under EUR 600,000 and you haven't specifically elected estimación directa normal, you're on simplificada by default." |
| 127 | |
| 128 | **Evaluate Q5:** |
| 129 | - **Madrid through Other** -> note for IRPF autonómica tramo. Continue. |
| 130 | - **País Vasco / Navarra** -> stop. "The foral territories (Bizkaia, Gipuzkoa, Araba, Navarra) have their own tax agencies and different income tax rules (IRPF foral). I'm set up for territorio común (AEAT) only. You need an asesor fiscal in your foral territory." |
| 131 | |
| 132 | **Evaluate Q6:** |
| 133 | - **First year / Second year / Third year** -> flag: retención reducida del 7% on professional invoices (instead of 15%) applies for the year of alta and the two following calendar years. |
| 134 | - **More than 3 years** -> standard 15% retención on professional invoices. |
| 135 | |
| 136 | **Total time:** ~45 seconds if the user taps through. |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## Section 3 -- The dump |
| 141 | |
| 142 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 143 | |
| 144 | **Example:** |
| 145 | |
| 146 | > Scope is good. Now upload everything you have for 2025 -- drop it all in at once: |
| 147 | > |
| 148 | > - Business bank statement(s) for all of 2025 (PDF or CSV) |
| 149 | > - Facturas emitidas (sales invoices issued in 2025) |
| 150 | > - Facturas recibidas (purchase invoices / receipts for business expenses) |
| 151 | > - Copies of Modelo 303 (IVA trimestral) filed for Q1-Q3 2025 |
| 152 | > - Modelo 130 copies (pagos fraccionados IRPF) filed for Q1-Q3 2025 |
| 153 | > - RETA recibos (monthly Social Security contribution receipts) |
| 154 | > - Prior year Modelo 100 (IRPF annual return) or borrador |
| 155 | > - Modelo 390 (IVA annual summary) from prior year |
| 156 | > - Any AEAT notifications or correspondence |
| 157 | > - Capital asset purchase receipts (computers, equipment, vehicles) |
| 158 | > - Home-related documents if claiming despacho en casa (mortgage interest, IBI, community fees, utility bills) |
| 159 | > - Anything else tax-related you have |
| 160 | > |
| 161 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 162 | |
| 163 | Then wait. Do not ask any other questions while waiting. |
| 164 | |
| 165 | **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. |
| 166 | |
| 167 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 168 | > Check these places: |
| 169 | > - Business bank: download 2025 statements as PDF or CSV |
| 170 | > - Sede electrónica AEAT (agenciatributaria.gob.es): download Modelo 303, 130, prior 100 |
| 171 | > - Email: search for "factura", "IVA", "IRPF", "AEAT", "Seguridad Social" |
| 172 | > - Your gestor or asesor fiscal from last year, if you had one |
| 173 | > - Import@ss portal: download RETA contribution history |
| 174 | > - Cloud storage for saved invoices |
| 175 | > |
| 176 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 177 | |
| 178 | --- |
| 179 | |
| 180 | ## Section 4 -- The inference pass |
| 181 | |
| 182 | When documents arrive, parse each one. For each document, extract: |
| 183 | |
| 184 | **Bank statement:** |
| 185 | - Total deposits (candidate gross receipts / ingresos) |
| 186 | - Recurring inflows (client payments with names) |
| 187 | - Outflows to AEAT (IVA payments, pagos fraccionados, with dates) |
| 188 | - Outflows to Seguridad Social / TGSS (RETA cuotas with dates and amounts) |
| 189 | - Outflows to suppliers (business expenses / gastos by category) |
| 190 | - Equipment purchases (potential capital items / inmovilizado) |
| 191 | - Transfers to personal account (owner draws) |
| 192 | - Rent payments (office or coworking space) |
| 193 | - SaaS / software subscriptions |
| 194 | - Insurance payments (responsabilidad civil, seguro de salud) |
| 195 | - Professional body fees (colegios profesionales) |
| 196 | |
| 197 | **Facturas emitidas (sales invoices):** |
| 198 | - Client names and amounts (base imponible) |
| 199 | - Whether IVA was charged (21%, 10%, 4%, or exento) |
| 200 | - Whether retención was applied (15% or 7% for new autónomos) |
| 201 | - Total turnover reconciliation against bank deposits |
| 202 | - Any EU clients (intracomunitarias -- reverse charge, ROI listing) |
| 203 | - Any non-EU clients (exportaciones de servicios) |
| 204 | - SAC / CNAE activity codes |
| 205 | |
| 206 | **Facturas recibidas (purchase invoices):** |
| 207 | - Expense category (gasto corriente vs inmovilizado) |
| 208 | - IVA soportado (deducible) amounts |
| 209 | - Supplier NIF/CIF |
| 210 | - Any items that are gastos no deducibles (entertainment/gifts above limits, fines) |
| 211 | - Any items above capital threshold (inmovilizado -- amortización) |
| 212 | |
| 213 | **Prior year Modelo 100:** |
| 214 | - Prior year IRPF liability |
| 215 | - Rendimiento neto de actividades económicas |
| 216 | - Filing status and applicable deductions |
| 217 | - Comunidad autónoma tramo rates applied |
| 218 | - Amortisation schedule (continuing depreciation) |
| 219 | |
| 220 | **Modelo 303 copies (quarterly IVA):** |
| 221 | - Quarterly base imponible and IVA devengado (output IVA) |
| 222 | - IVA soportado deducible (deductible input IVA) |
| 223 | - Result per quarter (a ingresar or a compensar) |
| 224 | - Any accumulated credit (saldo a compensar) |
| 225 | |
| 226 | **Modelo 130 copies (pagos fraccionados):** |
| 227 | - Quarterly rendimiento neto acumulado |
| 228 | - 20% pago fraccionado computed |
| 229 | - Retenciones acumuladas deducted |
| 230 | - Amount paid per quarter |
| 231 | |
| 232 | **RETA recibos:** |
| 233 | - Monthly RETA cuota paid (amount and month) |
| 234 | - Base de cotización (contribution base) |
| 235 | - Whether tarifa plana was applied (EUR 80/month for new autónomos in first year) |
| 236 | - Total annual RETA paid |
| 237 | |
| 238 | **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. |
| 239 | |
| 240 | --- |
| 241 | |
| 242 | ## Section 5 -- The confirmation |
| 243 | |
| 244 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 245 | |
| 246 | **Example summary message:** |
| 247 | |
| 248 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 249 | > |
| 250 | > **Identity** |
| 251 | > - María García López, NIF: 12345678A |
| 252 | > - Full-year Spanish resident (Madrid) |
| 253 | > - Autónoma, estimación directa simplificada |
| 254 | > - Alta en RETA since March 2023 (more than 3 years -- 15% retención) |
| 255 | > - IAE/CNAE: 8411 -- Servicios de consultoría de gestión |
| 256 | > |
| 257 | > **Ingresos (from bank statement + facturas emitidas)** |
| 258 | > - Ingresos brutos (base imponible): ~EUR 48,000 |
| 259 | > - Consultoría ABC SL: EUR 24,000 (retainer mensual) |
| 260 | > - Tech Solutions GmbH (Germany): EUR 12,000 (intracomunitaria, reverse charge) |
| 261 | > - Various domestic clients: EUR 12,000 |
| 262 | > - IVA repercutido (21%): ~EUR 7,560 (on domestic supplies) |
| 263 | > - Retenciones soportadas (15%): ~EUR 5,400 (on domestic professional invoices) |
| 264 | > |
| 265 | > **Gastos (from bank statement + facturas recibidas)** |
| 266 | > - Alquiler oficina / coworking: EUR 3,600 |
| 267 | > - Software / SaaS: EUR 1,200 |
| 268 | > - Seguro de responsabilidad civil: EUR 350 |
| 269 | > - Gestoría: EUR 600 |
| 270 | > - Teléfono / internet: EUR 720 (TBD -- need business use %) |
| 271 | > - Material de oficina: EUR 400 |
| 272 | > - Laptop: EUR 1,500 (June 2025) -- inmovilizado, amortización 25% |
| 273 | > - IVA soportado deducible: ~EUR 1,350 |
| 274 | > - Gastos de difícil justificación (5%): TBD after net income calc (max EUR 2,000) |
| 275 | > |
| 276 | > **RETA (from recibos)** |
| 277 | > - Monthly cuota: EUR 300 x 12 = EUR 3,600 |
| 278 | > - Base de cotización: EUR 1,000/month |
| 279 | > - Total 2025 RETA: EUR 3,600 (gasto deducible in IRPF) |
| 280 | > |
| 281 | > **Modelo 303 (IVA trimestral -- from filed returns)** |
| 282 | > - Q1-Q3 filed |
| 283 | > - Q4 outstanding |
| 284 | > - Accumulated IVA a compensar: EUR 0 |
| 285 | > |
| 286 | > **Modelo 130 (pagos fraccionados -- from filed returns)** |
| 287 | > - Q1-Q3 filed |
| 288 | > - Q4 outstanding |
| 289 | > - Pagos fraccionados acumulados: EUR 2,100 (20% of net x 3 quarters) |
| 290 | > |
| 291 | > **Retenciones (from facturas emitidas)** |
| 292 | > - Total retenciones soportadas: EUR 5,400 |
| 293 | > - These credit against final IRPF cuota |
| 294 | > |
| 295 | > **Prior year (from 2024 Modelo 100)** |
| 296 | > - 2024 IRPF cuota líquida: EUR 5,200 |
| 297 | > - 2024 rendimiento neto actividades: EUR 28,000 |
| 298 | > - Comunidad autónoma: Madrid |
| 299 | > |
| 300 | > **Flags I already see:** |
| 301 | > 1. Phone / internet -- need business use percentage |
| 302 | > 2. EU client (Germany) -- verify ROI inscription and Modelo 349 filing |
| 303 | > 3. Q4 2025 Modelo 303 not yet filed -- will prepare as part of this workflow |
| 304 | > 4. Q4 2025 Modelo 130 not yet filed -- will prepare |
| 305 | > 5. Home office -- not yet established if despacho en casa applies |
| 306 | > |
| 307 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 308 | |
| 309 | --- |
| 310 | |
| 311 | ## Section 6 -- Gap filling |
| 312 | |
| 313 | 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. |
| 314 | |
| 315 | **Things that usually cannot be inferred:** |
| 316 | |
| 317 | 1. **Home office (despacho en casa)** -- Cannot tell from documents whether a dedicated workspace exists. |
| 318 | 2. **Private use percentage** -- Phone, internet, vehicle business-use split. |
| 319 | 3. **Capital items from prior years** -- Continuing amortisation on assets acquired before 2025. |
| 320 | 4. **Exempt activities** -- Whether any income is IVA-exempt (medical, educational, financial). |
| 321 | 5. **Personal deductions** -- Aportaciones a planes de pensiones, deducción por vivienda habitual (if pre-2013 mortgage), deducción por maternidad, etc. |
| 322 | 6. **Other income** -- Employment income, rental income, capital gains, savings income. |
| 323 | |
| 324 | **Home office gap-filling example:** |
| 325 | |
| 326 | Call `ask_user_input_v0` with: |
| 327 | |
| 328 | ``` |
| 329 | Q: "Home office (despacho en casa)?" |
| 330 | Options: [ |
| 331 | "Dedicated room, used ONLY for work, declared in Modelo 036/037", |
| 332 | "Dedicated corner/desk, used ONLY for work", |
| 333 | "Shared space (kitchen table, living room)", |
| 334 | "Separate business premises (not at home)", |
| 335 | "No fixed workspace" |
| 336 | ] |
| 337 | ``` |
| 338 | |
| 339 | If option 1 -> ask for proportion of home used (m2 of office / m2 total). Deductible: proportional share of rent/mortgage interest, IBI, comunidad, utilities (30% of proportional share for suministros under simplificada). |
| 340 | If option 2 -> flag for reviewer: partial home office without Modelo 036 declaration is weak. |
| 341 | If option 3 -> "A shared space is very difficult to defend as despacho en casa with the AEAT. I'll skip this deduction." |
| 342 | If option 4 -> rent is already captured in expenses. No home office calculation needed. |
| 343 | If option 5 -> skip home office entirely. |
| 344 | |
| 345 | **Private use percentage example:** |
| 346 | |
| 347 | Call `ask_user_input_v0` with: |
| 348 | |
| 349 | ``` |
| 350 | Q: "Phone / internet -- business use?" |
| 351 | Options: [ |
| 352 | "Exclusive business line (separate from personal)", |
| 353 | "80%+ business use", |
| 354 | "50-80% business use", |
| 355 | "Under 50% business use" |
| 356 | ] |
| 357 | ``` |
| 358 | |
| 359 | For phone: if exclusive business line, 100% deductible. Otherwise apply percentage. |
| 360 | For vehicle: autónomos in estimación directa can deduct 50% IVA by default on vehicle (unless exclusively business use proven). Flag as standard treatment. |
| 361 | |
| 362 | **Personal deductions example:** |
| 363 | |
| 364 | Call `ask_user_input_v0` with: |
| 365 | |
| 366 | ``` |
| 367 | Q: "Aportaciones a planes de pensiones in 2025?" |
| 368 | Options: [ |
| 369 | "Yes -- I'll provide the amount", |
| 370 | "No aportaciones", |
| 371 | "Not sure" |
| 372 | ] |
| 373 | ``` |
| 374 | |
| 375 | If yes -> ask for amount (max EUR 1,500 individual, or EUR 8,500 if empresa plan). |
| 376 | |
| 377 | --- |
| 378 | |
| 379 | ## Section 7 -- The final handoff |
| 380 | |
| 381 | Once gap-filling is done, produce a final handoff message and hand off to `es-return-assembly`. |
| 382 | |
| 383 | **Example handoff message:** |
| 384 | |
| 385 | > Intake complete. Here's what's going to the return assembly: |
| 386 | > |
| 387 | > Autónoma, full-year Madrid resident, estimación directa simplificada. Ingresos brutos EUR 48,000, estimated rendimiento neto ~EUR 32,000 after gastos and RETA. |
| 388 | > |
| 389 | > I'm now going to run the full Spain return preparation. This covers: |
| 390 | > 1. Modelo 303 (IVA trimestral -- Q4 2025) |
| 391 | > 2. IRPF Modelo 100 (annual income tax return 2025) |
| 392 | > 3. RETA reconciliation (cotizaciones sociales) |
| 393 | > 4. Modelo 130 (pagos fraccionados -- Q4 2025) |
| 394 | > |
| 395 | > You'll get back: |
| 396 | > 1. An Excel working paper with all computations and live formulas |
| 397 | > 2. A reviewer brief with positions, citations, and flags for your asesor fiscal |
| 398 | > 3. A filing calendar with all upcoming deadlines |
| 399 | > |
| 400 | > Starting now. |
| 401 | |
| 402 | Then internally invoke `es-return-assembly` with the structured intake package. |
| 403 | |
| 404 | --- |
| 405 | |
| 406 | ## Section 8 -- Structured intake package (internal format) |
| 407 | |
| 408 | The downstream skill (`es-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 409 | |
| 410 | ```json |
| 411 | { |
| 412 | "jurisdiction": "ES", |
| 413 | "tax_year": 2025, |
| 414 | "taxpayer": { |
| 415 | "name": "", |
| 416 | "nif": "", |
| 417 | "residency": "full_year", |
| 418 | "comunidad_autonoma": "", |
| 419 | "alta_reta_date": "", |
| 420 | "years_as_autonomo": 0, |
| 421 | "estimacion": "directa_simplificada | directa_normal", |
| 422 | "entity_type": "autonomo", |
| 423 | "iae_cnae": "", |
| 424 | "retencion_rate": "15 | 7" |
| 425 | }, |
| 426 | "income": { |
| 427 | "ingresos_brutos": 0, |
| 428 | "iva_repercutido": 0, |
| 429 | "retenciones_soportadas": 0, |
| 430 | "intracomunitarias": 0, |
| 431 | "exportaciones": 0, |
| 432 | "other_income": 0, |
| 433 | "client_breakdown": [] |
| 434 | }, |
| 435 | "expenses": { |
| 436 | "gastos_deducibles": [], |
| 437 | "gastos_mixed_use": [], |
| 438 | "gastos_no_deducibles": [], |
| 439 | "inmovilizado": [], |
| 440 | "gastos_dificil_justificacion_pct": 5, |
| 441 | "total_gastos": 0 |
| 442 | }, |
| 443 | "iva": { |
| 444 | "modelo_303_filed": [], |
| 445 | "iva_devengado_total": 0, |
| 446 | "iva_soportado_deducible_total": 0, |
| 447 | "saldo_compensar": 0, |
| 448 | "exempt_activities": false, |
| 449 | "prorrata": false |
| 450 | }, |
| 451 | "reta": { |
| 452 | "monthly_cuota": 0, |
| 453 | "base_cotizacion": 0, |
| 454 | "months_alta": 12, |
| 455 | "tarifa_plana": false, |
| 456 | "total_reta_paid": 0 |
| 457 | }, |
| 458 | "pagos_fraccionados": { |
| 459 | "modelo_130_filed": [], |
| 460 | "total_pagos": 0, |
| 461 | "retenciones_deducted": 0 |
| 462 | }, |
| 463 | "prior_year": { |
| 464 | "irpf_cuota_liquida": 0, |
| 465 | "rendimiento_neto": 0, |
| 466 | "amortisation_schedule": [] |
| 467 | }, |
| 468 | "home_office": { |
| 469 | "qualifies": false, |
| 470 | "percentage_m2": 0, |
| 471 | "declared_036": false, |
| 472 | "rent_or_mortgage": 0, |
| 473 | "ibi": 0, |
| 474 | "comunidad": 0, |
| 475 | "suministros_total": 0 |
| 476 | }, |
| 477 | "private_use": { |
| 478 | "phone_business_pct": 0, |
| 479 | "internet_business_pct": 0, |
| 480 | "vehicle_business_pct": 0 |
| 481 | }, |
| 482 | "personal_deductions": { |
| 483 | "planes_pensiones": 0, |
| 484 | "vivienda_habitual": 0, |
| 485 | "maternidad": false, |
| 486 | "other": [] |
| 487 | }, |
| 488 | "open_flags": [], |
| 489 | "refusals_triggered": [], |
| 490 | "documents_received": [] |
| 491 | } |
| 492 | ``` |
| 493 | |
| 494 | --- |
| 495 | |
| 496 | ## Section 9 -- Refusal handling |
| 497 | |
| 498 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., company structure discovered in documents). |
| 499 | |
| 500 | When a refusal fires: |
| 501 | 1. Stop the workflow |
| 502 | 2. State the specific reason in one sentence |
| 503 | 3. Recommend the path forward (specific practitioner type) |
| 504 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 505 | |
| 506 | **Do not:** |
| 507 | - Apologise profusely |
| 508 | - Try to work around the refusal |
| 509 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 510 | - Continue silently |
| 511 | |
| 512 | **Sample refusal:** |
| 513 | |
| 514 | > Stop -- you operate through a Sociedad Limitada. I'm set up for autónomos (personas físicas) only. SLs file Impuesto sobre Sociedades (Modelo 200) with separate rules for administrator remuneration, dividends, and corporate tax. You need an asesor fiscal familiar with corporate returns. |
| 515 | > |
| 516 | > I can't help with this one. |
| 517 | |
| 518 | --- |
| 519 | |
| 520 | ## Section 10 -- Self-checks |
| 521 | |
| 522 | **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. |
| 523 | |
| 524 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 525 | |
| 526 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 527 | |
| 528 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 529 | |
| 530 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you pay RETA" after bank statements showed TGSS debits, check fails. |
| 531 | |
| 532 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 533 | |
| 534 | **Check IN7 -- Handoff to `es-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. |
| 535 | |
| 536 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned asesor fiscal signoff. |
| 537 | |
| 538 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 539 | |
| 540 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 541 | |
| 542 | **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. |
| 543 | |
| 544 | **Check IN12 -- Estimación directa type and retención rate established.** Simplificada vs normal confirmed, and 7% vs 15% retención determined, before handoff. |
| 545 | |
| 546 | --- |
| 547 | |
| 548 | ## Section 11 -- Performance targets |
| 549 | |
| 550 | For a prepared user (documents in a folder, ready to upload): |
| 551 | - **Refusal sweep**: 45 seconds (1-2 interactive turns) |
| 552 | - **Document upload**: 2 minutes (1 upload turn) |
| 553 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 554 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 555 | - **Handoff**: immediate |
| 556 | - **Total**: ~6 minutes |
| 557 | |
| 558 | For an unprepared user (has to go fetch documents): |
| 559 | - Refusal sweep: same |
| 560 | - Document discovery: 10-20 minutes offline |
| 561 | - Rest: same |
| 562 | - **Total**: 15-25 minutes |
| 563 | |
| 564 | --- |
| 565 | |
| 566 | ## Section 12 -- Cross-skill references |
| 567 | |
| 568 | **Inputs:** User-provided documents and answers. |
| 569 | |
| 570 | **Outputs:** Structured intake package consumed by `es-return-assembly`. |
| 571 | |
| 572 | **Downstream skills triggered (via es-return-assembly):** |
| 573 | - `spain-vat-return` -- Modelo 303 quarterly IVA return |
| 574 | - `es-income-tax` -- IRPF Modelo 100 annual return |
| 575 | - `es-social-contributions` -- RETA cotizaciones sociales |
| 576 | - `es-estimated-tax` -- Modelo 130 pagos fraccionados |
| 577 | |
| 578 | --- |
| 579 | |
| 580 | ### Change log |
| 581 | |
| 582 | - **v0.1 (April 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 583 | |
| 584 | ## End of Intake Skill v0.1 |
| 585 | |
| 586 | |
| 587 | --- |
| 588 | |
| 589 | ## Disclaimer |
| 590 | |
| 591 | 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 an asesor fiscal, gestor administrativo, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 592 | |
| 593 | 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. |
| 594 |
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 Spain tax returns AND mentions freelancing, self-employment, autónomo, working por cuenta propia, or independent professional activity. Trigger on phrases like "help me do my taxes", "prepare my Modelo 100", "I'm autónomo in Spain", "I'm a freelancer in Spain", "do my taxes as an autónomo", "prepare my IRPF return", or any similar phrasing where the user is a Spain-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Spain self-employed tax workflow -- every other skill in the stack (spain-vat-return, es-income-tax, es-social-contributions, es-estimated-tax, es-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. Spain full-year residents only; autónomos (self-employed individuals) only.
ESty-2025