Use this skill with your AI agent
Paste this skill into your AI agent's context, or save the file to your project. Works with any AI agent that reads markdown.
br-freelance-intake.md635 lines27.5 KB
v10Brazil
Not yet verified by an accountantContact accountant
| 1 | --- |
| 2 | name: br-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their Brazil tax returns AND mentions freelancing, self-employment, autônomo, MEI, microempreendedor individual, or Simples Nacional. Trigger on phrases like "help me do my taxes", "prepare my IRPF", "I'm a freelancer in Brazil", "I'm MEI", "I'm autônomo", "do my taxes as a contractor", "prepare my declaração de ajuste anual", or any similar phrasing where the user is a Brazil-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Brazil self-employed tax workflow -- every other skill in the stack (br-irpf, br-simples, br-inss, br-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. Brazil full-year residents only; self-employed individuals, MEI, and Simples Nacional sole proprietors. |
| 4 | version: 1.0 |
| 5 | jurisdiction: BR |
| 6 | category: orchestrator |
| 7 | --- |
| 8 | |
| 9 | # Brazil Self-Employed Intake Skill v1.0 |
| 10 | |
| 11 | ## What this file is |
| 12 | |
| 13 | The intake orchestrator for Brazil-resident self-employed individuals. Every downstream Brazil content skill (br-irpf, br-simples, br-inss, br-iss) and the assembly orchestrator (br-return-assembly) depend on this skill running first to produce a structured intake package. |
| 14 | |
| 15 | 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 `br-return-assembly`. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Design principles |
| 20 | |
| 21 | v1.0 follows the upload-first, inference-then-confirm pattern: |
| 22 | |
| 23 | 1. **Compact refusal sweep** using `ask_user_input_v0` -- 3 interactive questions, ~30 seconds. |
| 24 | 2. **Upload-first workflow** -- after the refusal check, the user dumps everything they have. |
| 25 | 3. **Inference pass** -- Claude parses every document and extracts as much as possible. |
| 26 | 4. **Gap-filling only** -- Claude asks the user ONLY about what is missing, ambiguous, or needs confirmation. |
| 27 | 5. **Single confirmation pass** at the end -- show the full picture, let the user correct anything wrong, hand off to downstream skills. |
| 28 | |
| 29 | Target: intake completes in 5 minutes for a prepared user, 15 minutes for a user who has to go fetch documents. |
| 30 | |
| 31 | ## Critical operating principles |
| 32 | |
| 33 | **Do not narrate the workflow.** Do not say "Phase 1," "Phase 2," "Now I'll ask you about deductions." Just do the work. |
| 34 | |
| 35 | **Do not ask questions that have already been answered.** If the refusal check established the user is MEI, do not later ask about business type. Track what is known. |
| 36 | |
| 37 | **Do not ask about things visible in uploaded documents.** If the bank statement shows monthly DAS payments, do not ask "did you pay DAS." Confirm what you see, do not re-ask. |
| 38 | |
| 39 | **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). |
| 40 | |
| 41 | **Prefer batching.** Ask 3 related questions in a single message when they do not depend on each other's answers. |
| 42 | |
| 43 | **Be terse but complete.** No hedging, no "let me know if you have questions," no "I hope this helps." |
| 44 | |
| 45 | **Exception for blocking decisions.** If a single question determines whether the user is in-scope or out-of-scope, ask it standalone. |
| 46 | |
| 47 | --- |
| 48 | |
| 49 | ## Section 1 -- The opening |
| 50 | |
| 51 | When triggered, respond with ONE message that: |
| 52 | |
| 53 | 1. One-line greeting (no paragraph of expectation-setting) |
| 54 | 2. One-line summary of the flow (scope check -> upload -> gaps -> handoff to return assembly) |
| 55 | 3. One-line reviewer reminder (must be reviewed by qualified contador before filing) |
| 56 | 4. Launch the refusal sweep immediately using `ask_user_input_v0` |
| 57 | |
| 58 | **Example first message:** |
| 59 | |
| 60 | > Vamos preparar suas declarações de 2025. Checagem rápida de escopo, depois você envia seus documentos, e eu preencho as lacunas. Tempo estimado: 10 minutos. |
| 61 | > |
| 62 | > Lembrete: tudo que eu produzir precisa ser revisado e assinado por um contador habilitado antes de protocolar qualquer coisa na Receita Federal. Não sou substituto de revisão profissional. |
| 63 | > |
| 64 | > Scope check: |
| 65 | |
| 66 | Then immediately call `ask_user_input_v0` with the refusal questions. |
| 67 | |
| 68 | **Do NOT:** |
| 69 | - Write a welcome paragraph |
| 70 | - Explain the phases |
| 71 | - Ask "are you ready to start" |
| 72 | - List what documents you will eventually need |
| 73 | - Give a disclaimer beyond the one reviewer line |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## Section 2 -- Refusal sweep (compact) |
| 78 | |
| 79 | Present the refusal sweep as a single `ask_user_input_v0` call with 3 questions, all single-select. |
| 80 | |
| 81 | **The 3 questions to ask first:** |
| 82 | |
| 83 | ``` |
| 84 | Q1: "Brazil residency in 2025?" |
| 85 | Options: ["Full year", "Part year (immigrated/emigrated)", "Did not live in Brazil"] |
| 86 | |
| 87 | Q2: "Business type?" |
| 88 | Options: ["MEI (microempreendedor individual)", "Simples Nacional (ME/EPP, not MEI)", "Autônomo / pessoa física (CPF, no CNPJ)", "Lucro Presumido", "Lucro Real", "Not sure"] |
| 89 | |
| 90 | Q3: "Employment status in 2025?" |
| 91 | Options: ["Fully self-employed (no employer)", "CLT employed + side self-employment", "CLT employed only (no self-employment income)"] |
| 92 | ``` |
| 93 | |
| 94 | **After the response, evaluate:** |
| 95 | |
| 96 | - **Q1 = Full year** -> continue |
| 97 | - **Q1 = Part year** -> stop. "Sou configurado apenas para residentes de ano inteiro no Brasil. Residentes parciais têm regras diferentes sobre renda de fonte mundial vs. fonte brasileira na Declaração de Saída Definitiva. Você precisa de um contador especializado em declarações de não-residente." |
| 98 | - **Q1 = Did not live in Brazil** -> stop. "Non-residents have different filing obligations. You need a contador who handles non-resident returns and Declaração de Saída Definitiva." |
| 99 | |
| 100 | - **Q2 = MEI** -> continue. Simplified path: DASN-SIMEI annual declaration + IRPF if obligated. |
| 101 | - **Q2 = Simples Nacional** -> continue. DAS calculation path + IRPF declaração de ajuste anual. |
| 102 | - **Q2 = Autônomo / pessoa física** -> continue. Carnê-leão monthly + IRPF ajuste anual path. |
| 103 | - **Q2 = Lucro Presumido** -> stop. "Lucro Presumido envolve IRPJ, CSLL, PIS/COFINS cumulativo com regras corporativas separadas. Você precisa de um contador familiarizado com apuração de Lucro Presumido." |
| 104 | - **Q2 = Lucro Real** -> stop. "Lucro Real é o regime tributário mais complexo do Brasil, com escrituração contábil completa, LALUR, e obrigações acessórias extensas. Você precisa de um contador especializado em Lucro Real." |
| 105 | - **Q2 = Not sure** -> decision tree follow-up: |
| 106 | "Você tem CNPJ? Se sim, qual o regime tributário no cartão CNPJ (Receita Federal)? |
| 107 | - CNPJ com 'MEI' → MEI |
| 108 | - CNPJ com 'Simples Nacional' → Simples |
| 109 | - CNPJ com 'Lucro Presumido' ou 'Lucro Real' → fora do escopo |
| 110 | - Sem CNPJ, recebe como pessoa física → Autônomo/PF" |
| 111 | |
| 112 | - **Q3 = Fully self-employed** -> continue |
| 113 | - **Q3 = CLT employed + side self-employment** -> continue with a flag: need to consolidate rendimentos tributáveis from both sources on IRPF. Informe de rendimentos from employer required. |
| 114 | - **Q3 = CLT employed only** -> stop. "Você não tem renda de trabalho autônomo. Este workflow é para autônomos e MEI. Seu empregador cuida da retenção de IRRF. Se você tem outras rendas (aluguel, investimentos), precisa de um contador para sua declaração completa de IRPF." |
| 115 | |
| 116 | **After Q1-Q3 pass, route based on Q2 answer and ask the second batch:** |
| 117 | |
| 118 | **For MEI:** |
| 119 | ``` |
| 120 | Q4: "MEI revenue in 2025?" |
| 121 | Options: ["Under R$81,000", "Over R$81,000 (exceeded MEI limit)", "Not sure"] |
| 122 | |
| 123 | Q5: "Did you have other income besides MEI in 2025?" |
| 124 | Options: ["No, MEI only", "Yes, CLT employment income", "Yes, rental income", "Yes, investment income", "Yes, multiple other sources"] |
| 125 | |
| 126 | Q6: "Marital status?" |
| 127 | Options: ["Single", "Married (comunhão parcial)", "Married (comunhão universal)", "Married (separação total)", "Stable union (união estável)"] |
| 128 | ``` |
| 129 | |
| 130 | **For Simples Nacional:** |
| 131 | ``` |
| 132 | Q4: "Simples Nacional revenue in 2025?" |
| 133 | Options: ["Under R$360,000 (ME)", "R$360,000 - R$4,800,000 (EPP)", "Over R$4,800,000 (exceeded Simples limit)", "Not sure"] |
| 134 | |
| 135 | Q5: "Primary activity type?" |
| 136 | Options: ["Services (Anexo III -- contabilidade, engenharia, etc.)", "Services (Anexo IV -- advocacia, limpeza, vigilância)", "Services (Anexo V -- TI, consultoria, publicidade)", "Commerce (Anexo I)", "Industry (Anexo II)"] |
| 137 | |
| 138 | Q6: "Marital status?" |
| 139 | Options: ["Single", "Married (comunhão parcial)", "Married (comunhão universal)", "Married (separação total)", "Stable union (união estável)"] |
| 140 | ``` |
| 141 | |
| 142 | **For Autônomo/PF:** |
| 143 | ``` |
| 144 | Q4: "How do you receive payments?" |
| 145 | Options: ["Directly from individuals (pessoa física) -- carnê-leão obrigatório", "From companies (pessoa jurídica) -- IRRF na fonte", "Both individuals and companies", "Via platforms (Uber, iFood, 99, etc.)"] |
| 146 | |
| 147 | Q5: "Do you pay INSS?" |
| 148 | Options: ["Yes, contribuinte individual (20% sobre remuneração)", "Yes, plano simplificado (11% sobre salário mínimo)", "Yes, MEI (via DAS)", "No / not sure"] |
| 149 | |
| 150 | Q6: "Marital status?" |
| 151 | Options: ["Single", "Married (comunhão parcial)", "Married (comunhão universal)", "Married (separação total)", "Stable union (união estável)"] |
| 152 | ``` |
| 153 | |
| 154 | **Evaluate Q4 (MEI):** |
| 155 | - Under R$81,000 -> continue. Standard DASN-SIMEI + IRPF if other income or assets trigger obligation. |
| 156 | - Over R$81,000 -> flag: MEI desenquadramento. If up to R$97,200 (20% excess), pay DAS complementar on excess. If over R$97,200, retroactive Simples Nacional from January. T2 for reviewer. |
| 157 | - Not sure -> "Check your total faturamento bruto in 2025. Sum all notas fiscais emitted. The MEI annual limit is R$81,000 (or proportional if you opened mid-year)." |
| 158 | |
| 159 | **Evaluate Q4 (Simples Nacional):** |
| 160 | - Under R$360,000 -> ME classification. Standard DAS. |
| 161 | - R$360,000-R$4,800,000 -> EPP classification. Standard DAS, higher sublimite may apply for ISS/ICMS. |
| 162 | - Over R$4,800,000 -> stop. "Faturamento acima de R$4,8 milhões exclui do Simples Nacional. Você precisa migrar para Lucro Presumido ou Real. Consulte um contador." |
| 163 | |
| 164 | **Total time:** ~45 seconds if the user taps through. |
| 165 | |
| 166 | --- |
| 167 | |
| 168 | ## Section 3 -- The dump |
| 169 | |
| 170 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 171 | |
| 172 | **Example (Autônomo path):** |
| 173 | |
| 174 | > Escopo confirmado. Agora envie tudo que você tem de 2025 -- tudo de uma vez: |
| 175 | > |
| 176 | > - Extratos bancários de 2025 (conta PF e/ou PJ) -- CSV ou PDF |
| 177 | > - Recibos de pagamento / notas fiscais emitidas em 2025 |
| 178 | > - Recibos de despesas dedutíveis (livro-caixa) |
| 179 | > - Comprovantes de pagamento do carnê-leão (DARFs código 0190) |
| 180 | > - Informe de rendimentos de pessoa jurídica (se recebeu de empresas) |
| 181 | > - Informe de rendimentos de instituição financeira (bancos, corretoras) |
| 182 | > - Comprovante de INSS recolhido (GPS ou DAS) |
| 183 | > - Declaração de IRPF do ano anterior (2024) |
| 184 | > - Notas fiscais de aquisição de bens (computador, equipamento, veículo) |
| 185 | > - Comprovantes de despesas médicas e educação (para deduções legais) |
| 186 | > - Comprovantes de previdência privada (PGBL) |
| 187 | > - Qualquer correspondência da Receita Federal |
| 188 | > - Qualquer outro documento fiscal que você tenha |
| 189 | > |
| 190 | > Não se preocupe em organizar -- eu descubro o que cada arquivo é. Arraste e solte quando estiver pronto. |
| 191 | |
| 192 | **Example (MEI path):** |
| 193 | |
| 194 | > Escopo confirmado. Envie tudo que você tem de 2025: |
| 195 | > |
| 196 | > - Relatório mensal de faturamento (ou notas fiscais emitidas) |
| 197 | > - Comprovantes de pagamento do DAS mensal |
| 198 | > - Extratos bancários (conta PJ e PF) |
| 199 | > - DASN-SIMEI do ano anterior (se tiver) |
| 200 | > - Informe de rendimentos de outras fontes (emprego CLT, investimentos) |
| 201 | > - Comprovante de despesas médicas e educação |
| 202 | > - Comprovantes de previdência privada (PGBL) |
| 203 | > - Qualquer correspondência da Receita Federal |
| 204 | |
| 205 | Then wait. Do not ask any other questions while waiting. |
| 206 | |
| 207 | **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. |
| 208 | |
| 209 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 210 | > Verifique estes lugares: |
| 211 | > - App do banco: baixe extratos de 2025 como PDF ou CSV |
| 212 | > - Portal e-CAC da Receita Federal: baixe declarações anteriores, informes de rendimentos |
| 213 | > - Email: pesquise por "nota fiscal", "DARF", "DAS", "informe de rendimentos" |
| 214 | > - Seu contador do ano passado, se teve um |
| 215 | > - App da previdência (Meu INSS): extrato de contribuições |
| 216 | > - Corretora de investimentos: informe de rendimentos |
| 217 | > |
| 218 | > Volte quando tiver algo para enviar. Trabalho com o que você trouxer. |
| 219 | |
| 220 | --- |
| 221 | |
| 222 | ## Section 4 -- The inference pass |
| 223 | |
| 224 | When documents arrive, parse each one. For each document, extract: |
| 225 | |
| 226 | **Bank statement:** |
| 227 | - Total deposits (candidate gross receipts) |
| 228 | - Recurring inflows (client payments with names/CPF/CNPJ) |
| 229 | - Outflows to Receita Federal (DARFs -- carnê-leão código 0190, IRPF código 0211, IRPJ) |
| 230 | - Outflows for DAS (MEI or Simples) |
| 231 | - INSS payments (GPS or via DAS) |
| 232 | - ISS payments (if applicable) |
| 233 | - Outflows to suppliers (business expenses) |
| 234 | - Equipment purchases |
| 235 | - Transfers between PJ and PF accounts |
| 236 | - Medical expenses (potential deduction) |
| 237 | - Education expenses (potential deduction) |
| 238 | - PGBL contributions (previdência privada) |
| 239 | |
| 240 | **Notas fiscais emitidas:** |
| 241 | - Client names/CNPJ and amounts |
| 242 | - Service codes (CNAE / código de serviço municipal) |
| 243 | - ISS retained or paid |
| 244 | - IRRF retained (1.5% for services to PJ) |
| 245 | - Total faturamento reconciliation against bank deposits |
| 246 | - Any nota fiscal de produto (ICMS/IPI implications) |
| 247 | |
| 248 | **Informes de rendimentos (from companies):** |
| 249 | - Rendimentos tributáveis |
| 250 | - IRRF retido na fonte |
| 251 | - Contribuição previdenciária retida |
| 252 | - 13º salário, férias (if CLT) |
| 253 | |
| 254 | **Informe de rendimentos de instituição financeira:** |
| 255 | - Rendimentos de aplicações financeiras (renda fixa, renda variável) |
| 256 | - IR retido na fonte sobre aplicações |
| 257 | - Saldo em conta corrente e poupança on 31/12/2025 |
| 258 | |
| 259 | **Livro-caixa (expense book):** |
| 260 | - Despesas dedutíveis: aluguel de escritório, material de escritório, conta de telefone/internet (parcela profissional), transporte, despesas com empregados (se autônomo com até 1 empregado doméstico) |
| 261 | - Receitas mensais |
| 262 | - Monthly balance (receitas minus despesas) |
| 263 | |
| 264 | **Prior year IRPF:** |
| 265 | - Prior year rendimentos tributáveis |
| 266 | - Prior year deduções legais |
| 267 | - Prior year imposto devido and pago |
| 268 | - Bens e direitos (assets and rights -- carried forward) |
| 269 | - Dívidas e ônus reais (debts) |
| 270 | |
| 271 | **DAS/GPS payment receipts:** |
| 272 | - Monthly DAS payments (MEI: R$75.90 base 2025; Simples: variable by faturamento and anexo) |
| 273 | - GPS payments (autônomo: 20% sobre remuneração or 11% plano simplificado) |
| 274 | |
| 275 | **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. |
| 276 | |
| 277 | --- |
| 278 | |
| 279 | ## Section 5 -- The confirmation |
| 280 | |
| 281 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 282 | |
| 283 | **Example summary message (Autônomo path):** |
| 284 | |
| 285 | > Aqui está o que extraí dos seus documentos. Confira e me diga o que está errado. |
| 286 | > |
| 287 | > **Identidade** |
| 288 | > - Maria Silva, solteira |
| 289 | > - Residente no Brasil ano inteiro (São Paulo - SP) |
| 290 | > - Autônoma / pessoa física, CPF 123.456.789-00 |
| 291 | > - Atividade: consultoria em tecnologia |
| 292 | > |
| 293 | > **Receita (do extrato bancário + notas fiscais)** |
| 294 | > - Rendimentos tributáveis recebidos de PJ: ~R$120,000 |
| 295 | > - TechCorp Ltda: R$72,000 (mensal) |
| 296 | > - ConsultBR SA: R$36,000 (projetos) |
| 297 | > - Diversos PF: R$12,000 |
| 298 | > - IRRF retido na fonte (PJ): ~R$1,800 |
| 299 | > |
| 300 | > **Carnê-leão (rendimentos de PF)** |
| 301 | > - Rendimentos de PF: R$12,000 (R$1,000/mês) |
| 302 | > - Carnê-leão pago (DARFs 0190): R$0 (mensal abaixo da faixa de isenção individual) |
| 303 | > - Verificar: carnê-leão deveria ter sido calculado mensalmente sobre total de rendimentos PF |
| 304 | > |
| 305 | > **Despesas dedutíveis -- Livro-caixa** |
| 306 | > - Aluguel de escritório: R$14,400 |
| 307 | > - Internet/telefone: R$3,600 (TBD -- percentual profissional) |
| 308 | > - Software/SaaS: R$4,800 |
| 309 | > - Material de escritório: R$1,200 |
| 310 | > - Total livro-caixa: ~R$24,000 |
| 311 | > |
| 312 | > **INSS** |
| 313 | > - Contribuinte individual (20%): R$1,412.00/mês x 12 = R$16,944 (teto) |
| 314 | > - Verificar: contribuição sobre teto do INSS (R$7,786.02 em 2025 x 20% = R$1,557.20/mês) |
| 315 | > |
| 316 | > **Deduções legais (IRPF)** |
| 317 | > - Despesas médicas: R$8,400 (sem limite) |
| 318 | > - Despesas de educação: R$3,561.50 (limite 2025) |
| 319 | > - PGBL: R$9,600 (verificar limite 12% da renda bruta tributável) |
| 320 | > - Dependentes: nenhum |
| 321 | > |
| 322 | > **Bens e direitos (do IRPF anterior)** |
| 323 | > - Apartamento: R$450,000 (custo aquisição) |
| 324 | > - Veículo: R$85,000 |
| 325 | > - Conta corrente + poupança 31/12/2025: R$42,000 |
| 326 | > - Investimentos (CDB, fundos): R$120,000 |
| 327 | > |
| 328 | > **Flags que já identifiquei:** |
| 329 | > 1. Telefone/internet -- precisa do percentual profissional |
| 330 | > 2. Carnê-leão sobre rendimentos de PF -- verificar se foi calculado e pago mensalmente |
| 331 | > 3. PGBL -- verificar se não excede 12% da renda bruta tributável |
| 332 | > 4. IRRF retido na fonte -- confirmar valores com informes de rendimentos oficiais |
| 333 | > 5. Livro-caixa não pode exceder a receita (despesas limitadas à receita mensal) |
| 334 | > |
| 335 | > **Está correto? Responda "ok" ou me diga o que corrigir.** |
| 336 | |
| 337 | --- |
| 338 | |
| 339 | ## Section 6 -- Gap filling |
| 340 | |
| 341 | 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. |
| 342 | |
| 343 | **Things that usually cannot be inferred:** |
| 344 | |
| 345 | 1. **Modelo de declaração** -- Completa (deduções legais) vs simplificada (desconto de 20%, limite R$16,754.34 em 2025). |
| 346 | 2. **Dependentes** -- Cannot always tell from documents. |
| 347 | 3. **Pensão alimentícia** -- Judicial or by escritura pública. |
| 348 | 4. **Home office** -- Percentage of home used professionally for livro-caixa. |
| 349 | 5. **Private use percentage** -- Phone, internet, vehicle. |
| 350 | 6. **Bens e direitos updates** -- New acquisitions or sales in 2025. |
| 351 | 7. **Dívidas e ônus reais** -- Debts over R$5,000 on 31/12/2025. |
| 352 | 8. **Rendimentos isentos** -- Poupança, dividends from PJ (until new rules), FGTS, seguro desemprego. |
| 353 | 9. **Rendimentos do exterior** -- If any foreign-source income. |
| 354 | |
| 355 | **Modelo de declaração:** |
| 356 | |
| 357 | Call `ask_user_input_v0` with: |
| 358 | |
| 359 | ``` |
| 360 | Q: "Which IRPF model?" |
| 361 | Options: [ |
| 362 | "Completa (deduções legais -- I have medical, education, PGBL, dependents)", |
| 363 | "Simplificada (desconto de 20%, max R$16,754.34)", |
| 364 | "Calculate both and pick the better one" |
| 365 | ] |
| 366 | ``` |
| 367 | |
| 368 | If option 3 -> compute both models and select the one with lower imposto devido. Flag as T2 to confirm. |
| 369 | |
| 370 | **Dependentes:** |
| 371 | |
| 372 | Call `ask_user_input_v0` with: |
| 373 | |
| 374 | ``` |
| 375 | Q: "Dependentes for IRPF 2025?" |
| 376 | Options: [ |
| 377 | "None", |
| 378 | "1 dependent", |
| 379 | "2 dependents", |
| 380 | "3+ dependents (tell me details)" |
| 381 | ] |
| 382 | ``` |
| 383 | |
| 384 | If dependents -> ask for name, CPF, date of birth, relationship (filho, cônjuge, companheiro, pai/mãe). Deduction: R$2,275.08 per dependent (2025). |
| 385 | |
| 386 | **Livro-caixa percentages:** |
| 387 | |
| 388 | Call `ask_user_input_v0` with: |
| 389 | |
| 390 | ``` |
| 391 | Q: "Home office -- percentual de uso profissional?" |
| 392 | Options: [ |
| 393 | "100% -- escritório dedicado separado da residência", |
| 394 | "75-100% -- cômodo exclusivo para trabalho", |
| 395 | "50-75% -- cômodo compartilhado", |
| 396 | "Under 50%", |
| 397 | "No home office (separate business premises)" |
| 398 | ] |
| 399 | ``` |
| 400 | |
| 401 | Flag all private-use percentages as T2 -- contador must confirm. |
| 402 | |
| 403 | --- |
| 404 | |
| 405 | ## Section 7 -- The final handoff |
| 406 | |
| 407 | Once gap-filling is done, produce a final handoff message and hand off to `br-return-assembly`. |
| 408 | |
| 409 | **Decision tree for routing:** |
| 410 | |
| 411 | - **MEI** -> DASN-SIMEI (simplified annual declaration) + IRPF (if obligated: other income > isenção, bens > R$800,000, rendimentos isentos > R$200,000, etc.) |
| 412 | - **Simples Nacional** -> DAS reconciliation + IRPF declaração de ajuste anual (pró-labore as rendimentos tributáveis, distributed profit as isento) |
| 413 | - **Autônomo/PF** -> Carnê-leão reconciliation + IRPF declaração de ajuste anual (livro-caixa deductions) |
| 414 | |
| 415 | **Example handoff message:** |
| 416 | |
| 417 | > Intake completo. Seguindo para a montagem das declarações: |
| 418 | > |
| 419 | > Autônoma/PF, solteira, CPF, residente ano inteiro. Rendimentos tributáveis R$120,000, despesas livro-caixa R$24,000, renda líquida estimada ~R$96,000. |
| 420 | > |
| 421 | > Vou preparar o pacote completo: |
| 422 | > 1. Reconciliação do carnê-leão mensal (DARFs código 0190) |
| 423 | > 2. IRPF -- Declaração de Ajuste Anual (modelo completa ou simplificada) |
| 424 | > 3. Reconciliação INSS |
| 425 | > 4. ISS (se aplicável) |
| 426 | > |
| 427 | > Você receberá: |
| 428 | > 1. Uma planilha Excel com todos os cálculos e fórmulas |
| 429 | > 2. Um resumo para o revisor com posições, citações legais, e alertas |
| 430 | > 3. Um calendário de obrigações com prazos e valores |
| 431 | > |
| 432 | > Começando agora. |
| 433 | |
| 434 | Then internally invoke `br-return-assembly` with the structured intake package. |
| 435 | |
| 436 | --- |
| 437 | |
| 438 | ## Section 8 -- Structured intake package (internal format) |
| 439 | |
| 440 | The downstream skill (`br-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 441 | |
| 442 | ```json |
| 443 | { |
| 444 | "jurisdiction": "BR", |
| 445 | "tax_year": 2025, |
| 446 | "taxpayer": { |
| 447 | "name": "", |
| 448 | "cpf": "", |
| 449 | "cnpj": "", |
| 450 | "birth_year": 0, |
| 451 | "marital_status": "single | married_comunhao_parcial | married_comunhao_universal | married_separacao | uniao_estavel", |
| 452 | "residency": "full_year", |
| 453 | "business_type": "mei | simples_nacional | autonomo_pf", |
| 454 | "cnae_principal": "", |
| 455 | "employment_status": "self_employed | employed_plus_side", |
| 456 | "municipality": "", |
| 457 | "state": "" |
| 458 | }, |
| 459 | "income": { |
| 460 | "rendimentos_tributaveis_pj": 0, |
| 461 | "rendimentos_tributaveis_pf": 0, |
| 462 | "irrf_retido": 0, |
| 463 | "rendimentos_isentos": 0, |
| 464 | "rendimentos_sujeitos_tributacao_exclusiva": 0, |
| 465 | "faturamento_bruto_mei_simples": 0, |
| 466 | "client_breakdown": [] |
| 467 | }, |
| 468 | "expenses": { |
| 469 | "livro_caixa": [], |
| 470 | "total_livro_caixa": 0, |
| 471 | "mixed_use": [], |
| 472 | "despesas_medicas": 0, |
| 473 | "despesas_educacao": 0, |
| 474 | "pgbl": 0, |
| 475 | "pensao_alimenticia": 0 |
| 476 | }, |
| 477 | "carne_leao": { |
| 478 | "monthly_receipts_pf": [], |
| 479 | "monthly_darfs_paid": [], |
| 480 | "total_paid": 0 |
| 481 | }, |
| 482 | "inss": { |
| 483 | "contribution_type": "contribuinte_individual_20 | plano_simplificado_11 | mei_das", |
| 484 | "monthly_payments": [], |
| 485 | "total_paid": 0 |
| 486 | }, |
| 487 | "mei": { |
| 488 | "faturamento_bruto": 0, |
| 489 | "das_payments": [], |
| 490 | "das_total": 0, |
| 491 | "parcela_isenta_servicos": 0.32, |
| 492 | "parcela_isenta_comercio": 0.08, |
| 493 | "parcela_isenta_industria": 0.08, |
| 494 | "parcela_isenta_transporte": 0.16 |
| 495 | }, |
| 496 | "simples_nacional": { |
| 497 | "faturamento_bruto_12m": 0, |
| 498 | "anexo": "I | II | III | IV | V", |
| 499 | "fator_r": 0, |
| 500 | "das_payments": [], |
| 501 | "das_total": 0, |
| 502 | "pro_labore": 0, |
| 503 | "distribuicao_lucros_isenta": 0 |
| 504 | }, |
| 505 | "deducoes_legais": { |
| 506 | "dependentes": [], |
| 507 | "despesas_medicas": 0, |
| 508 | "despesas_educacao": 0, |
| 509 | "pgbl": 0, |
| 510 | "pensao_alimenticia": 0, |
| 511 | "inss": 0 |
| 512 | }, |
| 513 | "bens_e_direitos": [], |
| 514 | "dividas_e_onus": [], |
| 515 | "prior_year": { |
| 516 | "imposto_devido": 0, |
| 517 | "rendimentos_tributaveis": 0, |
| 518 | "bens_e_direitos": [] |
| 519 | }, |
| 520 | "modelo_declaracao": "completa | simplificada | calculate_both", |
| 521 | "open_flags": [], |
| 522 | "refusals_triggered": [], |
| 523 | "documents_received": [] |
| 524 | } |
| 525 | ``` |
| 526 | |
| 527 | --- |
| 528 | |
| 529 | ## Section 9 -- Refusal handling |
| 530 | |
| 531 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., Lucro Presumido structure discovered in documents). |
| 532 | |
| 533 | When a refusal fires: |
| 534 | 1. Stop the workflow |
| 535 | 2. State the specific reason in one sentence |
| 536 | 3. Recommend the path forward (specific practitioner type) |
| 537 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 538 | |
| 539 | **Do not:** |
| 540 | - Apologize profusely |
| 541 | - Try to work around the refusal |
| 542 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 543 | - Continue silently |
| 544 | |
| 545 | **Refusals:** |
| 546 | |
| 547 | **R-BR-1 -- Lucro Real.** "Stop -- Lucro Real é o regime tributário mais complexo do Brasil, com escrituração contábil completa, LALUR (Livro de Apuração do Lucro Real), ECF, ECD, e obrigações acessórias extensas (SPED). Você precisa de um contador especializado em Lucro Real." |
| 548 | |
| 549 | **R-BR-2 -- Import/export companies.** "Stop -- empresas de importação/exportação envolvem regimes aduaneiros especiais, Siscomex, drawback, e tributação complexa de ICMS/IPI/PIS/COFINS. Você precisa de um contador com expertise em comércio exterior." |
| 550 | |
| 551 | **R-BR-3 -- S.A. structures.** "Stop -- sociedades anônimas (S.A.) têm obrigações específicas com a CVM, publicação de balanços, e regras distintas de tributação. Você precisa de um contador especializado em S.A." |
| 552 | |
| 553 | **Sample refusal:** |
| 554 | |
| 555 | > Stop -- você tem apuração por Lucro Real. Sou configurado para MEI, Simples Nacional, e autônomos pessoa física apenas. Lucro Real requer escrituração contábil completa, LALUR, e apuração trimestral/anual de IRPJ e CSLL. Você precisa de um contador especializado. |
| 556 | > |
| 557 | > Não posso ajudar com esse caso. |
| 558 | |
| 559 | --- |
| 560 | |
| 561 | ## Section 10 -- Self-checks |
| 562 | |
| 563 | **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. |
| 564 | |
| 565 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 566 | |
| 567 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 568 | |
| 569 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 570 | |
| 571 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "você pagou INSS" after the bank statement showed GPS payments, check fails. |
| 572 | |
| 573 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 574 | |
| 575 | **Check IN7 -- Handoff to `br-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. |
| 576 | |
| 577 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned contador signoff. |
| 578 | |
| 579 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 580 | |
| 581 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 582 | |
| 583 | **Check IN11 -- Total user-facing turn count is low.** Target: 8 turns or fewer from start to handoff for a prepared user. More than 12 turns for a normal intake is a check failure. |
| 584 | |
| 585 | **Check IN12 -- Business type was established and routing applied.** MEI vs Simples vs Autônomo was confirmed before inference, as it changes the entire downstream path. |
| 586 | |
| 587 | --- |
| 588 | |
| 589 | ## Section 11 -- Performance targets |
| 590 | |
| 591 | For a prepared user (documents in a folder, ready to upload): |
| 592 | - **Refusal sweep**: 45 seconds (1-2 interactive turns) |
| 593 | - **Document upload**: 2 minutes (1 upload turn) |
| 594 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 595 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 596 | - **Handoff**: immediate |
| 597 | - **Total**: ~6 minutes |
| 598 | |
| 599 | For an unprepared user (has to go fetch documents): |
| 600 | - Refusal sweep: same |
| 601 | - Document discovery: 10-20 minutes offline |
| 602 | - Rest: same |
| 603 | - **Total**: 15-25 minutes |
| 604 | |
| 605 | --- |
| 606 | |
| 607 | ## Section 12 -- Cross-skill references |
| 608 | |
| 609 | **Inputs:** User-provided documents and answers. |
| 610 | |
| 611 | **Outputs:** Structured intake package consumed by `br-return-assembly`. |
| 612 | |
| 613 | **Downstream skills triggered (via br-return-assembly):** |
| 614 | - `br-irpf` -- Declaração de Ajuste Anual (IRPF) |
| 615 | - `br-simples` -- DAS calculation and reconciliation (MEI/Simples) |
| 616 | - `br-inss` -- INSS contribution reconciliation |
| 617 | - `br-iss` -- ISS municipal tax (if applicable) |
| 618 | |
| 619 | --- |
| 620 | |
| 621 | ### Change log |
| 622 | |
| 623 | - **v1.0 (May 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 624 | |
| 625 | ## End of Intake Skill v1.0 |
| 626 | |
| 627 | |
| 628 | --- |
| 629 | |
| 630 | ## Disclaimer |
| 631 | |
| 632 | 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 CPA, EA, tax attorney, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 633 | |
| 634 | 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. |
| 635 |
Run this skill, then get an accountant to check it
After running the full skill pack in your AI agent, 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.
Verification status
Research-verified
Drafted from authoritative sources (tax authority sites, Big-4 summaries). Awaiting credentialed sign-off.
Needs section-by-section practitioner review to reach accountant-verified.
Section review progress
0/19
About
ALWAYS USE THIS SKILL when a user asks for help preparing their Brazil tax returns AND mentions freelancing, self-employment, autônomo, MEI, microempreendedor individual, or Simples Nacional. Trigger on phrases like "help me do my taxes", "prepare my IRPF", "I'm a freelancer in Brazil", "I'm MEI", "I'm autônomo", "do my taxes as a contractor", "prepare my declaração de ajuste anual", or any similar phrasing where the user is a Brazil-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Brazil self-employed tax workflow -- every other skill in the stack (br-irpf, br-simples, br-inss, br-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. Brazil full-year residents only; self-employed individuals, MEI, and Simples Nacional sole proprietors.
BRty-2025
Use this skill
This skill is open source and free to use in any AI agent. Copy it, download it, or clone the repo. If you find an error, report an issue — a licensed accountant will review.