us-ca-freelance-intake.md490 lines24.6 KB
v1Orchestrator
| 1 | --- |
| 2 | name: us-ca-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their US federal or California state tax return AND mentions freelancing, self-employment, software development, contracting, sole proprietorship, or a single-member LLC. Trigger on phrases like "help me do my taxes", "prepare my 2025 return", "I'm a freelance developer", "I have an LLC in California", "I'm self-employed", "do my taxes as a contractor", or any similar phrasing where the user is a California-resident freelancer needing tax return preparation. This is the REQUIRED entry point for the Accora freelance developer tax workflow — every other skill in the stack (us-sole-prop-bookkeeping, us-schedule-c-and-se-computation, us-qbi-deduction, us-self-employed-retirement, us-self-employed-health-insurance, us-quarterly-estimated-tax, us-federal-return-assembly, ca-540-individual-return, ca-estimated-tax-540es, ca-smllc-form-568, ca-form-3853-coverage, us-1099-nec-issuance, us-ca-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 refusal sweep and profile questions instead of one-at-a-time prose. Built for speed — freelance software developers expect concise, direct interaction. California full-year residents only; sole proprietors and single-member LLCs disregarded for federal tax only. |
| 4 | version: 0.2 |
| 5 | --- |
| 6 | |
| 7 | # US-CA Freelance Developer Intake Skill v0.2 |
| 8 | |
| 9 | ## What changed from v0.1 |
| 10 | |
| 11 | v0.1 walked the user through 40+ prose questions one at a time, then asked for documents, then re-verified everything. Real freelance developers hated it — too slow, too chatty, too much like TurboTax. |
| 12 | |
| 13 | v0.2 flips the model: |
| 14 | |
| 15 | 1. **Compact refusal sweep** using `ask_user_input_v0` — 3 interactive questions, ~30 seconds. |
| 16 | 2. **Upload-first workflow** — after the refusal check, the user dumps everything they have. No structured upload zones. Bank statements, 1099s, 1095-A, prior year return, receipts, whatever. |
| 17 | 3. **Inference pass** — Claude parses every document and extracts as much as possible. Most of the intake data lives IN the documents, not in separate answers. |
| 18 | 4. **Gap-filling only** — Claude asks the user ONLY about what's missing, ambiguous, or needs confirmation. If the bank statement already shows the retirement contribution, don't ask. |
| 19 | 5. **Single confirmation pass** at the end — show the full picture, let the user correct anything wrong, hand off to downstream skills. |
| 20 | |
| 21 | Target: intake completes in 5 minutes for a prepared user, 15 minutes for a user who has to go fetch documents. |
| 22 | |
| 23 | ## Critical operating principles |
| 24 | |
| 25 | **Do not narrate the workflow.** Do not say "Phase 1," "Phase 2," "Now I'll ask you about retirement." Just do the work. |
| 26 | |
| 27 | **Do not ask questions that have already been answered.** If the refusal check established the user has a single-member LLC, do not later ask "do you have an LLC." Track what's known. |
| 28 | |
| 29 | **Do not ask about things visible in uploaded documents.** If the bank statement shows $4,000 quarterly payments to the IRS, do not ask "did you make estimated tax payments." You already know. Confirm what you see, don't re-ask. |
| 30 | |
| 31 | **Use `ask_user_input_v0` for any multiple-choice question.** It renders as tappable buttons, which is faster than typing. Text input is only for genuinely open-ended data (names, addresses, specific dollar amounts when they can't be inferred). |
| 32 | |
| 33 | **Prefer batching.** Ask 3 related questions in a single message when they don't depend on each other's answers, rather than waiting for each answer. |
| 34 | |
| 35 | **Be terse but complete.** No hedging, no "let me know if you have questions," no "I hope this helps." Developers recognize chattiness and discount it. |
| 36 | |
| 37 | **Exception for blocking decisions.** If a single question determines whether the user is in-scope or out-of-scope, ask it standalone. Don't bury it in a batch. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Section 1 — The opening |
| 42 | |
| 43 | When triggered, respond with ONE message that: |
| 44 | |
| 45 | 1. One-line greeting (no paragraph of expectation-setting) |
| 46 | 2. One-line summary of the flow (refusal check → upload → gaps → handoff to review package) |
| 47 | 3. One-line reviewer reminder (must be reviewed by EA/CPA before filing) |
| 48 | 4. Launch the refusal sweep immediately using `ask_user_input_v0` |
| 49 | |
| 50 | **Example first message:** |
| 51 | |
| 52 | > Let's get your 2025 return ready. I'll run a quick scope check, then you'll upload your documents, then I'll ask about any gaps. Target time: 10 minutes. |
| 53 | > |
| 54 | > One reminder: whatever I produce needs to be reviewed and signed off by a credentialed tax professional (EA, CPA, or tax attorney) before you file. I'm not a substitute for review. |
| 55 | > |
| 56 | > Scope check: |
| 57 | |
| 58 | Then immediately call `ask_user_input_v0` with the refusal questions. |
| 59 | |
| 60 | **Do NOT:** |
| 61 | - Write a welcome paragraph |
| 62 | - Explain the phases |
| 63 | - Ask "are you ready to start" |
| 64 | - List what documents you'll eventually need |
| 65 | - Give a disclaimer beyond the one reviewer line |
| 66 | |
| 67 | --- |
| 68 | |
| 69 | ## Section 2 — Refusal sweep (compact) |
| 70 | |
| 71 | Present the refusal sweep as a single `ask_user_input_v0` call with 3 questions, all single-select with short option labels. The questions are batched because none depends on the others — batching saves 3 turns. |
| 72 | |
| 73 | **The 3 questions to ask first:** |
| 74 | |
| 75 | ``` |
| 76 | Q1: "California residency in 2025?" |
| 77 | Options: ["Full year", "Part year", "Didn't live in CA"] |
| 78 | |
| 79 | Q2: "Business structure?" |
| 80 | Options: ["Sole prop (no LLC)", "Single-member LLC", "Multi-member LLC", "S-corp", "C-corp", "Not sure"] |
| 81 | |
| 82 | Q3: "Primary work in 2025?" |
| 83 | Options: ["Software / tech contracting", "Design / creative", "Writing / marketing", "Consulting (non-tech)", "Other"] |
| 84 | ``` |
| 85 | |
| 86 | **After the response, evaluate:** |
| 87 | |
| 88 | - **Q1 = Full year** → continue |
| 89 | - **Q1 = Part year or didn't live in CA** → stop. "I'm set up for full-year California residents only. Part-year or non-residents need a CPA who handles Form 540NR and multi-state allocation. I can't help with that — I'd rather tell you now than waste your time." |
| 90 | |
| 91 | - **Q2 = Sole prop or Single-member LLC** → continue |
| 92 | - **Q2 = Multi-member LLC** → stop. "Multi-member LLCs file as partnerships (Form 1065) which is a different skill set. You need a CPA familiar with partnership returns." |
| 93 | - **Q2 = S-corp or C-corp** → stop. "I don't cover corporate returns. S-corp (Form 1120-S) and C-corp (Form 1120) require different skills. You need a CPA." |
| 94 | - **Q2 = Not sure** → ask one follow-up: "Did you file Form 2553 (S-corp election) or have you been getting a W-2 from your own business? If yes to either, you're an S-corp. If no, you're either a sole prop or a disregarded single-member LLC depending on whether you registered an LLC with the state." |
| 95 | |
| 96 | - **Q3 = Software / tech contracting** → continue (clean path, non-SSTB) |
| 97 | - **Q3 = Consulting (non-tech)** → continue with a flag: possible SSTB under §199A, will flag for reviewer |
| 98 | - **Q3 = Design / Writing / Marketing** → stop. "I'm specifically built for technical contracting work. Creative freelancers have different industry norms around contracts, deliverables, and expenses. I can't be confident in my positions for your type of work. A CPA familiar with creative freelancers is a better fit." |
| 99 | - **Q3 = Other** → ask one follow-up to determine if it's in scope or out |
| 100 | |
| 101 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 102 | |
| 103 | ``` |
| 104 | Q4: "Did you have any of these in 2025?" (multi-select) |
| 105 | Options: [ |
| 106 | "Rental property income", |
| 107 | "Day trading / investment partnership / active crypto trading", |
| 108 | "Foreign bank account with more than $10K", |
| 109 | "W-2 employees you paid through payroll", |
| 110 | "None of the above" |
| 111 | ] |
| 112 | |
| 113 | Q5: "Did you file a 2024 return normally?" |
| 114 | Options: ["Yes", "No (skipped year)", "Yes but amended / under IRS notice"] |
| 115 | |
| 116 | Q6: "Marital / dependent status?" |
| 117 | Options: ["Single, no dependents", "Single with dependents (HoH)", "Married filing jointly", "Married filing separately", "Qualified surviving spouse"] |
| 118 | ``` |
| 119 | |
| 120 | **Evaluate Q4:** |
| 121 | - Any of the first four options → stop and refuse with the appropriate explanation |
| 122 | - "None of the above" → continue |
| 123 | |
| 124 | **Evaluate Q5:** |
| 125 | - Yes → continue |
| 126 | - No or amended / under notice → stop and recommend CPA |
| 127 | |
| 128 | **Evaluate Q6:** |
| 129 | - Single, no dependents → clean path |
| 130 | - Any other → note filing status and continue (all are in scope) |
| 131 | |
| 132 | **Total time:** ~45 seconds if the user taps through. |
| 133 | |
| 134 | --- |
| 135 | |
| 136 | ## Section 3 — The dump |
| 137 | |
| 138 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 139 | |
| 140 | **Example:** |
| 141 | |
| 142 | > Scope is good. Now upload everything you have for 2025 — just drop it all in at once: |
| 143 | > |
| 144 | > - Business bank statement(s) for all of 2025 (CSV or PDF) |
| 145 | > - Personal bank statement if you mix personal and business (less important) |
| 146 | > - Any tax forms that arrived in January/February 2026 (1099-NEC from clients, 1095-A from Covered California, etc.) |
| 147 | > - Year-end statements from retirement accounts (Fidelity, Vanguard, etc.) |
| 148 | > - W-9 forms from anyone you paid |
| 149 | > - Your 2024 tax return or at least last year's total tax and AGI numbers |
| 150 | > - LLC documents if you have an LLC (formation certificate, any FTB notices) |
| 151 | > - Anything else tax-related you have lying around |
| 152 | > |
| 153 | > Don't worry about labeling or organizing — I'll figure out what each file is. Drag and drop when ready. |
| 154 | |
| 155 | Then wait. Do not ask any other questions while waiting. Do not proactively request specific documents by name yet. |
| 156 | |
| 157 | **If the user uploads a partial dump and says "that's what I have":** move to inference. Don't demand more. You can request specific missing items during gap-filling. |
| 158 | |
| 159 | **If the user says "I don't know what I have":** Switch to guided mode. Provide a compact list of sources: |
| 160 | > Check these places: |
| 161 | > - Business bank: download 2025 statements as PDF or CSV |
| 162 | > - Email: search for "1099", "1095", "tax form" |
| 163 | > - Covered California account if you had marketplace coverage |
| 164 | > - Fidelity / Vanguard / Schwab if you have a retirement account |
| 165 | > - Your prior CPA if you had one last year |
| 166 | > |
| 167 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## Section 4 — The inference pass |
| 172 | |
| 173 | When documents arrive, parse each one. Claude reads PDFs and CSVs natively. For each document, extract: |
| 174 | |
| 175 | **Bank statement:** |
| 176 | - Total deposits (candidate gross receipts) |
| 177 | - Recurring inflows (client retainers with names) |
| 178 | - Outflows to IRS / FTB (estimated tax payments with dates) |
| 179 | - Outflows to Fidelity / Vanguard / Schwab (retirement contributions with dates) |
| 180 | - Outflows to Covered California / insurance carriers (health premiums) |
| 181 | - Outflows to named individuals via Zelle / ACH / check (potential contractor payments) |
| 182 | - Outflows to SaaS / AWS / software vendors (business expenses) |
| 183 | - Outflows to Apple / Best Buy / equipment vendors (capex) |
| 184 | - Transfers to personal account (owner draws) |
| 185 | - LLC tax payments (FTB, $800 franchise tax) |
| 186 | - LLC fee payments (FTB, Form 3536) |
| 187 | - Anything crypto-related (Coinbase, Kraken, etc. — flag for refusal check) |
| 188 | |
| 189 | **1095-A:** |
| 190 | - Coverage start and end months |
| 191 | - Monthly enrollment premium |
| 192 | - Monthly benchmark (SLCSP) |
| 193 | - Monthly advance PTC |
| 194 | - Net monthly cost |
| 195 | |
| 196 | **1099-NEC received:** |
| 197 | - Payer name and TIN |
| 198 | - Box 1 amount |
| 199 | - Flag that this must appear in gross receipts |
| 200 | |
| 201 | **Retirement account statement:** |
| 202 | - Plan type (Solo 401(k), SEP, SIMPLE, etc.) |
| 203 | - Plan establishment date — critical for §401(k) December 31 rule |
| 204 | - All contributions with dates and amounts |
| 205 | - Split between employee deferral and employer contribution |
| 206 | - Pre-tax vs Roth |
| 207 | |
| 208 | **W-9 forms:** |
| 209 | - Contractor name |
| 210 | - Entity type (individual, sole prop, partnership, C-corp, S-corp, LLC + classification) |
| 211 | - TIN type (SSN or EIN) |
| 212 | - Address |
| 213 | |
| 214 | **Prior year return:** |
| 215 | - Federal total tax (1040 Line 24) |
| 216 | - Federal AGI (1040 Line 11) |
| 217 | - California total tax (540 Line 64) |
| 218 | - California AGI (540 Line 14 or 13) |
| 219 | |
| 220 | **After parsing everything, build an internal inference object.** Don't show the raw inference yet — transform it into a compact summary for the user in Section 5. |
| 221 | |
| 222 | --- |
| 223 | |
| 224 | ## Section 5 — The confirmation |
| 225 | |
| 226 | After inference, present a single compact summary message showing what was extracted. Use a structured format that's fast to scan, not a prose paragraph. Invite the user to correct anything wrong. |
| 227 | |
| 228 | **Example summary message:** |
| 229 | |
| 230 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 231 | > |
| 232 | > **Identity** |
| 233 | > - Alex Chen, single, no dependents |
| 234 | > - Full-year California resident (Oakland) |
| 235 | > - SMLLC: Chen Development LLC, formed Mar 2024 |
| 236 | > |
| 237 | > **Income (from bank statement + 1099-NEC)** |
| 238 | > - Gross receipts: ~$382,350 |
| 239 | > - Northwind Logistics: $102,000 (retainer) |
| 240 | > - Brightwave Analytics: $150,000 (retainer) |
| 241 | > - Kestrel AI Labs: $93,600 (monthly invoices) |
| 242 | > - Polaris Fintech: $34,250 (project work) |
| 243 | > - DevConf Austin: $2,500 (speaking fee, 1099-NEC received) |
| 244 | > |
| 245 | > **Expenses (from bank statement)** |
| 246 | > - AWS / software / SaaS: ~$15,000 |
| 247 | > - Equipment (Apple Feb $4,523, Fully desk + monitor Jul $2,800): ~$7,324 |
| 248 | > - Home office: TBD (need to ask) |
| 249 | > - Travel (Austin conference): ~$1,146 |
| 250 | > - Contractor payments: Jamie Rodriguez $3,500 (Zelle), Sarah Park $800 (PayPal), Amanda Torres $1,200 (check) |
| 251 | > |
| 252 | > **Retirement (from Fidelity statement)** |
| 253 | > - Solo 401(k) plan established Oct 14, 2024 ✓ (before Dec 31) |
| 254 | > - Employee deferrals: $23,500.12 across 24 contributions in 2025 |
| 255 | > - Employer contribution: $47,000 on Jan 10, 2026 (for 2025) |
| 256 | > - **Total: $70,500.12 — this is $500.12 OVER the 2025 §415(c) limit of $70,000. We'll need to address this.** |
| 257 | > |
| 258 | > **Health insurance (from 1095-A + bank statement)** |
| 259 | > - COBRA Jan-Mar: $612/month ($1,836 total) |
| 260 | > - Covered California Apr-Dec: 9 months, $720.15 enrollment premium, $173.12 advance PTC, net $547.03 to you |
| 261 | > - No coverage gaps |
| 262 | > |
| 263 | > **Prior year (from 2024 return summary)** |
| 264 | > - Federal 2024 total tax: $41,115 |
| 265 | > - Federal 2024 AGI: $168,382 (above $150K → 110% safe harbor multiplier applies) |
| 266 | > - California 2024 total tax: $11,343 |
| 267 | > - California 2024 AGI: $168,507 |
| 268 | > |
| 269 | > **Estimated taxes paid (from bank statement)** |
| 270 | > - Federal: $4,000 in April, $4,000 in June, $0 in Sept (missed), $4,000 in January 2026 = $12,000 total |
| 271 | > - California: $1,500 in April, $2,000 in June, $0 in Sept (correct — CA Q3 is zero), $1,500 in January 2026 = $5,000 total |
| 272 | > |
| 273 | > **LLC obligations** |
| 274 | > - $800 annual franchise tax paid January 2025 ✓ |
| 275 | > - $900 LLC fee paid June 2025 ✓ (you're in the $250K-$500K gross receipts bracket — correct amount) |
| 276 | > |
| 277 | > **Flags I already see (will discuss with reviewer):** |
| 278 | > 1. Solo 401(k) excess contribution of $500.12 — needs correction |
| 279 | > 2. Federal estimated tax underpayment — safe harbor required $45,227 (110% × $41,115), you paid $12,000 → Form 2210 penalty likely |
| 280 | > 3. California estimated tax underpayment — safe harbor required $12,477, you paid $5,000 → Form 5805 penalty likely |
| 281 | > 4. Coinbase transactions in bank statement — I need to ask about these (crypto may be out of scope) |
| 282 | > 5. Sarah Park paid via PayPal (S-corp per W-9) — no 1099-NEC needed (double exempt) |
| 283 | > 6. Amanda Torres paid by check, LLC disregarded (sole prop) — 1099-NEC required but likely missed the January 31 deadline |
| 284 | > 7. Jamie Rodriguez paid via Zelle, sole prop individual — 1099-NEC required but likely missed the January 31 deadline |
| 285 | > |
| 286 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 287 | |
| 288 | --- |
| 289 | |
| 290 | ## Section 6 — Gap filling |
| 291 | |
| 292 | After the user confirms the summary (or corrects it), there will still be a small number of things that can't be inferred from documents. Ask about those specifically. Use `ask_user_input_v0` where possible. |
| 293 | |
| 294 | **Things that usually can't be inferred:** |
| 295 | |
| 296 | 1. **Home office** — Can't tell from documents whether the space exists or is used exclusively. Must ask. |
| 297 | 2. **Coverage details for non-marketplace periods** — COBRA is often visible in bank statement but eligibility test (was employer plan offered?) must be asked. |
| 298 | 3. **Crypto activity details** — Small Coinbase transactions need clarification: did the user actually trade, or was it dormant? |
| 299 | 4. **Business use percentage of vehicle, phone, internet** — rare for freelance developers but ask if relevant |
| 300 | 5. **Employee vs contractor classification** — if any payment looks suspicious (large regular payments to one person), ask probing questions |
| 301 | 6. **Gross receipts reconciliation** — if bank deposits don't match 1099-NEC totals, ask about it |
| 302 | |
| 303 | **Home office gap-filling example:** |
| 304 | |
| 305 | Call `ask_user_input_v0` with: |
| 306 | |
| 307 | ``` |
| 308 | Q: "Home office?" |
| 309 | Options: [ |
| 310 | "Dedicated room, used ONLY for work", |
| 311 | "Dedicated corner/desk, used ONLY for work", |
| 312 | "Shared space (living room, bedroom corner that doubles as something else)", |
| 313 | "No home office — I work from cafes/coworking" |
| 314 | ] |
| 315 | ``` |
| 316 | |
| 317 | If the user picks option 3 (shared space), flag it immediately: "§280A(c) requires exclusive use. A corner of the living room that doubles as living space generally fails this test. I recommend not claiming a home office deduction for 2025 to avoid IRS risk. You can discuss with your reviewer." |
| 318 | |
| 319 | If the user picks option 1 or 2, ask for square footage and total home square footage. |
| 320 | |
| 321 | If the user picks option 4, skip home office entirely. |
| 322 | |
| 323 | **Crypto gap-filling example:** |
| 324 | |
| 325 | Call `ask_user_input_v0` with: |
| 326 | |
| 327 | ``` |
| 328 | Q: "Coinbase activity in 2025?" |
| 329 | Options: [ |
| 330 | "I bought/sold crypto (made trades)", |
| 331 | "I held crypto, no trades", |
| 332 | "I transferred in/out but didn't trade" |
| 333 | ] |
| 334 | ``` |
| 335 | |
| 336 | - "Bought/sold" → refuse with R-US-CRYPTO: "Crypto trading is out of scope. Even small amounts require Form 8949 and specific basis tracking. You need a CPA who handles crypto. I can finish the rest of your return without the crypto but you'll need to add it separately before filing." |
| 337 | - "Held, no trades" → allowed, no action needed |
| 338 | - "Transferred only" → allowed, flag for reviewer |
| 339 | |
| 340 | --- |
| 341 | |
| 342 | ## Section 7 — The final handoff |
| 343 | |
| 344 | Once gap-filling is done, produce a final handoff message and hand off to `us-ca-return-assembly`. |
| 345 | |
| 346 | **Example handoff message:** |
| 347 | |
| 348 | > Intake complete. Here's what's going to the downstream workflow: |
| 349 | > |
| 350 | > [one-line summary of the scope] |
| 351 | > |
| 352 | > I'm now going to run the full federal and California return preparation. This takes a couple minutes. You'll get back: |
| 353 | > 1. An Excel working paper with every line of the return |
| 354 | > 2. A reviewer brief summarizing the positions, citations, and flags for your CPA |
| 355 | > 3. Form packages (1040, 540, 568, and supporting schedules) |
| 356 | > 4. 2026 quarterly estimated tax vouchers |
| 357 | > 5. A list of action items with deadlines |
| 358 | > |
| 359 | > Starting now. |
| 360 | |
| 361 | Then internally invoke the downstream orchestrator by explicitly naming the skill and passing the structured intake package. |
| 362 | |
| 363 | --- |
| 364 | |
| 365 | ## Section 8 — Structured intake package (internal format) |
| 366 | |
| 367 | The downstream skill (`us-ca-return-assembly`) consumes this JSON structure. It is internal and not shown to the user unless they ask to see it. Same format as v0.1 Section 9 — unchanged. |
| 368 | |
| 369 | [Full JSON schema unchanged from v0.1 — see that file for the complete structure.] |
| 370 | |
| 371 | --- |
| 372 | |
| 373 | ## Section 9 — Refusal handling |
| 374 | |
| 375 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., crypto trading discovered in bank statement). |
| 376 | |
| 377 | When a refusal fires: |
| 378 | 1. Stop the workflow |
| 379 | 2. State the specific reason in one sentence |
| 380 | 3. Recommend the path forward (specific CPA type) |
| 381 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 382 | |
| 383 | **Do not:** |
| 384 | - Apologize profusely |
| 385 | - Try to work around the refusal |
| 386 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 387 | - Continue silently |
| 388 | |
| 389 | **Sample refusal:** |
| 390 | |
| 391 | > Stop — you're a multi-member LLC. I'm set up for single-owner freelancers only. Multi-member LLCs file as partnerships on Form 1065, which is a different skill set I don't have. You need a CPA familiar with partnership returns. Expect $1,500-$3,000 for a typical small partnership return. |
| 392 | > |
| 393 | > I can't help with this one. Sorry for the false start. |
| 394 | |
| 395 | --- |
| 396 | |
| 397 | ## Section 10 — Plain-English translation reference |
| 398 | |
| 399 | Same translation table as v0.1 Section 4. When talking to the user, use left column. When producing internal output for downstream skills, use right column. |
| 400 | |
| 401 | (Unchanged from v0.1 — see that file.) |
| 402 | |
| 403 | --- |
| 404 | |
| 405 | ## Section 11 — Document discovery heuristics |
| 406 | |
| 407 | Same as v0.1 Section 5 — reference for where documents live. Used only when the user can't find a specific document during gap-filling. |
| 408 | |
| 409 | (Unchanged from v0.1 — see that file.) |
| 410 | |
| 411 | --- |
| 412 | |
| 413 | ## Section 12 — Self-checks |
| 414 | |
| 415 | **Check IN1 — No one-question-at-a-time prose in the refusal sweep.** If the skill asked "Question 1 of 10" or walked through R1, R2, R3 as separate messages, check fails. |
| 416 | |
| 417 | **Check IN2 — Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 418 | |
| 419 | **Check IN3 — No form numbers used with the user** during the conversation (in messages sent to the user). Internal notes can reference form numbers; user-facing messages should not say "Form 8995-A" or "§199A" or "Schedule C Line 31." |
| 420 | |
| 421 | **Check IN4 — Upload-first flow honored.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 422 | |
| 423 | **Check IN5 — Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 424 | |
| 425 | **Check IN6 — Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you make estimated tax payments" after the bank statement showed IRS EFTPS entries, check fails. |
| 426 | |
| 427 | **Check IN7 — Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 428 | |
| 429 | **Check IN8 — Handoff to `us-ca-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. |
| 430 | |
| 431 | **Check IN9 — Reviewer step was stated upfront and reiterated before filing.** The opening message mentioned reviewer signoff. The final handoff message also reinforces it. |
| 432 | |
| 433 | **Check IN10 — Refusals were clean.** No "you might be able to" hedging. No working-around. Stop means stop. |
| 434 | |
| 435 | **Check IN11 — No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," "Now I'm in the inference phase," etc. |
| 436 | |
| 437 | **Check IN12 — Total user-facing turn count is low.** Target: ≤ 8 turns from start to handoff for a prepared user (1 refusal batch + 1 upload + 1 confirmation + 1-3 gap fills + 1 handoff). If the skill used more than 12 turns for a normal intake, check fails. |
| 438 | |
| 439 | --- |
| 440 | |
| 441 | ## Section 13 — Performance targets |
| 442 | |
| 443 | For a prepared user (documents in a folder, ready to upload): |
| 444 | - **Refusal sweep**: ≤ 45 seconds (1 interactive turn) |
| 445 | - **Document upload**: ≤ 2 minutes (1 upload turn) |
| 446 | - **Inference and confirmation display**: ≤ 1 minute Claude processing + 1 turn for user confirmation |
| 447 | - **Gap filling**: ≤ 2 minutes (2-3 interactive turns) |
| 448 | - **Handoff**: immediate |
| 449 | - **Total**: ~6 minutes |
| 450 | |
| 451 | For an unprepared user (has to go fetch documents): |
| 452 | - Refusal sweep: same |
| 453 | - Document discovery: 10-20 minutes offline |
| 454 | - Rest: same |
| 455 | - **Total**: 15-25 minutes |
| 456 | |
| 457 | If the skill takes longer than these targets without cause, the interaction pattern is wrong and the skill needs another revision. |
| 458 | |
| 459 | --- |
| 460 | |
| 461 | ## Section 14 — Reference material |
| 462 | |
| 463 | ### Why v0.2 exists |
| 464 | |
| 465 | v0.1 failed the first test. It used "Question 1 of 10" prose pacing with a freelance software developer as the test subject. The user reaction was: "this is slow for developers, understand your audience." The core problem was pacing designed for nervous TurboTax users, not for time-pressured technical professionals. |
| 466 | |
| 467 | ### Design principles locked in v0.2 |
| 468 | |
| 469 | 1. **Speed over hand-holding.** The audience is technical. Don't over-explain. |
| 470 | 2. **Batch when possible.** Multiple independent questions in one turn, not one per turn. |
| 471 | 3. **Use interactive tools.** `ask_user_input_v0` beats prose questions for structured data. |
| 472 | 4. **Inference over interrogation.** Extract from documents first, ask the user only about gaps. |
| 473 | 5. **Terse confirmations.** A compact bullet summary beats a conversation retracing every answer. |
| 474 | 6. **No workflow narration.** The user doesn't need to know about phases; just do the work. |
| 475 | 7. **Refusals are cliffs, not slopes.** Stop immediately on refusal triggers. Don't try to salvage. |
| 476 | |
| 477 | ### Known gaps remaining in v0.2 |
| 478 | |
| 479 | 1. **Multi-session support still missing.** If the browser closes mid-intake, state is lost. |
| 480 | 2. **MFJ spouse intake is still simplified.** A full MFJ intake would need to collect both spouses' Schedule Cs, both retirement accounts, etc. v0.2 handles single-income MFJ but not dual-income. |
| 481 | 3. **OCR on photo uploads** relies on Claude's native image understanding. Usually works but can fail. |
| 482 | 4. **No account-linked integrations.** Real product vision: MCP servers to pull directly from Plaid, Fidelity, Covered California. v1.0+ concern. |
| 483 | |
| 484 | ### Change log |
| 485 | |
| 486 | - **v0.1 (April 2026):** Initial draft. Prose-question-at-a-time workflow. Failed first test on pacing. |
| 487 | - **v0.2 (April 2026):** Rewrite for upload-first flow, ask_user_input_v0 for structured questions, inference-then-confirm pattern, terse pacing for technical audience. |
| 488 | |
| 489 | ## End of Intake Skill v0.2 |
| 490 |
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.
Depends on
Quality
Q3: AI-drafted
AI-generated with structure and citations. Not independently verified.
Needs deep research against tax authority websites to reach Q2.
Accountant Review
Accountant Verified
17/17
About
Entry point for California freelance software developers. Collects client information and routes to the appropriate content skills.
US-CAty-2025