us-federal-return-assembly.md463 lines22.6 KB
v1Federal
| 1 | --- |
| 2 | name: us-federal-return-assembly |
| 3 | description: Tier 2 orchestrator skill that assembles the complete federal income tax return package for US freelance software developers filing as sole proprietors or single-member LLCs disregarded for federal tax. Sequences the upstream content skills (bookkeeping, SE computation, retirement, SE health insurance, QBI, estimated tax) in dependency order, resolves circular computations between SE health insurance and retirement contributions, produces Form 1040 with all required schedules (Schedule 1, Schedule 2, Schedule 3, Schedule C, Schedule SE, Schedule D if needed, Form 8829, Form 4562, Form 8995 or 8995-A, Form 8962 if marketplace coverage, Form 2210 if penalty, Form 7206), performs cross-form reconciliation checks, and produces the final reviewer package. Does not itself compute tax amounts — delegates to upstream content skills. MUST be loaded alongside us-tax-workflow-base v0.2 or later and all content skills it orchestrates. Federal only. |
| 4 | version: 0.2 |
| 5 | --- |
| 6 | |
| 7 | # US Federal Return Assembly Skill v0.2 |
| 8 | |
| 9 | ## CRITICAL EXECUTION DIRECTIVE — READ FIRST |
| 10 | |
| 11 | **When this skill is invoked, either directly or via `us-ca-return-assembly`, execute the full workflow without pausing for user permission.** |
| 12 | |
| 13 | - **Do NOT ask "how deep should I go"** or "do you want the full package." The answer is always: full package, all deliverables, every step. |
| 14 | - **Do NOT announce your token budget.** Run the work. |
| 15 | - **Do NOT pause between content skills for status updates.** One consolidated status message at the end is fine. Per-skill status between each upstream skill is noise. |
| 16 | - **Self-checks are targets, not blockers.** If a check fails, flag it in the reviewer brief and continue. Do not halt the workflow for ambiguous edge cases — the reviewer handles those. |
| 17 | - **If you run out of context mid-execution,** finish the computation work (numbers, positions, flags) first, then produce whatever formatted deliverables you can, and state clearly at the end which were not produced. Partial output with an honest status beats a question asking permission. |
| 18 | - **Primary source citations belong in the final reviewer brief,** not in intermediate computation steps. Compute first, cite once at the end. |
| 19 | |
| 20 | **Failure mode to avoid:** halting mid-execution to ask the user a meta-question about workflow pacing. If you feel the urge to ask "how should I proceed," pick the most defensible path and proceed, flagging the decision in the reviewer brief. |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## What this file is |
| 25 | |
| 26 | This is an **orchestrator** skill, not a content skill. It does not contain tax computation rules — those live in the content skills (`us-sole-prop-bookkeeping`, `us-schedule-c-and-se-computation`, `us-self-employed-retirement`, `us-self-employed-health-insurance`, `us-qbi-deduction`, `us-quarterly-estimated-tax`). This skill's job is to: |
| 27 | |
| 28 | 1. **Sequence** the content skills in dependency order |
| 29 | 2. **Resolve** the circular computations (specifically the SE health insurance + retirement + QBI interaction) |
| 30 | 3. **Assemble** the final Form 1040 and all supporting schedules |
| 31 | 4. **Cross-check** that amounts flowing between forms tie out |
| 32 | 5. **Produce** the reviewer package (Form 1040, schedules, Excel working paper, reviewer brief) |
| 33 | |
| 34 | **Tax year:** 2025 |
| 35 | |
| 36 | **The reviewer is still the customer.** The orchestrator produces a package ready for a credentialed reviewer to review and sign. It does not file the return. |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Section 1 — Scope |
| 41 | |
| 42 | Taxpayers covered: same as the upstream content skills. US sole proprietors and SMLLC disregarded for federal tax, filing Form 1040 for tax year 2025. |
| 43 | |
| 44 | Out of scope: anything refused by the base or any content skill. |
| 45 | |
| 46 | --- |
| 47 | |
| 48 | ## Section 2 — The dependency graph |
| 49 | |
| 50 | The content skills must be run in a specific order because of forward references and circular dependencies. |
| 51 | |
| 52 | ``` |
| 53 | Bookkeeping (us-sole-prop-bookkeeping) |
| 54 | └→ produces: classified transactions, Schedule C line totals, owner draws |
| 55 | │ |
| 56 | ↓ |
| 57 | SE Computation (us-schedule-c-and-se-computation) |
| 58 | └→ consumes: bookkeeping output |
| 59 | └→ produces: Schedule C Line 31, Schedule SE Line 12, Schedule 1 Line 15 (half SE tax) |
| 60 | │ |
| 61 | ↓ |
| 62 | Retirement (us-self-employed-retirement) |
| 63 | └→ consumes: Schedule C Line 31, half of SE tax |
| 64 | └→ produces: Schedule 1 Line 16 (retirement contribution deduction) |
| 65 | │ |
| 66 | ↓ |
| 67 | SE Health Insurance (us-self-employed-health-insurance) |
| 68 | └→ consumes: Schedule C Line 31, half of SE tax, Schedule 1 Line 16 |
| 69 | └→ produces: Schedule 1 Line 17 (SE health insurance deduction) |
| 70 | │ |
| 71 | ↓ |
| 72 | QBI (us-qbi-deduction) |
| 73 | └→ consumes: Schedule C Line 31, Schedule 1 Lines 15/16/17, taxable income before QBI |
| 74 | └→ produces: QBI deduction (Form 1040 Line 13) |
| 75 | │ |
| 76 | ↓ |
| 77 | Federal Return Assembly (this skill) |
| 78 | └→ assembles: Form 1040 with all schedules |
| 79 | └→ cross-checks: amounts tie across forms |
| 80 | │ |
| 81 | ↓ |
| 82 | Estimated Tax (us-quarterly-estimated-tax) |
| 83 | └→ consumes: Form 1040 Line 24 (total tax) from this year |
| 84 | └→ produces: Form 2210 penalty (if any), 2026 installment plan |
| 85 | ``` |
| 86 | |
| 87 | **The circular subproblem:** QBI depends on taxable income before QBI, which depends on all deductions including QBI itself if done naively. The IRS resolves this by defining "taxable income before QBI" as taxable income computed without the QBI deduction. So the order is: |
| 88 | 1. Compute all other adjustments to income (Schedule 1 Lines 11-25) |
| 89 | 2. Compute AGI (Form 1040 Line 11) |
| 90 | 3. Compute taxable income before QBI (AGI minus standard/itemized deduction) |
| 91 | 4. Apply QBI using that taxable income as the threshold test |
| 92 | 5. Compute final taxable income (taxable income before QBI minus QBI deduction) |
| 93 | |
| 94 | **The SE health insurance + PTC iterative problem:** Already handled inside the SE health insurance skill via Rev. Proc. 2014-41. The orchestrator does not re-solve it. |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | ## Section 3 — Workflow steps |
| 99 | |
| 100 | ### Step 1: Trigger intake and profile the taxpayer |
| 101 | |
| 102 | Run the base intake (Tier 1 refusal sweep plus Tier 2 structured questions). Confirm the taxpayer is in scope. Confirm the reviewer is identified. |
| 103 | |
| 104 | ### Step 2: Run bookkeeping skill |
| 105 | |
| 106 | Produce classified Schedule C transactions and line totals. Verify the 10 bookkeeping self-checks pass. |
| 107 | |
| 108 | ### Step 3: Run SE computation skill |
| 109 | |
| 110 | Produce Schedule C Line 31, Schedule SE, and Schedule 1 Line 15. Verify the 17 computation self-checks pass. |
| 111 | |
| 112 | ### Step 4: Run retirement skill |
| 113 | |
| 114 | Produce Schedule 1 Line 16. Verify retirement self-checks pass. |
| 115 | |
| 116 | ### Step 5: Run SE health insurance skill (with PTC iteration if applicable) |
| 117 | |
| 118 | Produce Schedule 1 Line 17. Verify self-checks pass. If PTC iteration did not converge, halt and escalate to reviewer. |
| 119 | |
| 120 | ### Step 6: Compute other Schedule 1 items |
| 121 | |
| 122 | Other Schedule 1 lines that may be relevant: |
| 123 | - Line 11: Educator expenses (not usually applicable for freelance developers) |
| 124 | - Line 12: Certain business expenses of reservists, performing artists, fee-basis government officials (not applicable) |
| 125 | - Line 13: HSA deduction (if the taxpayer has an HSA-qualified HDHP) |
| 126 | - Line 14: Moving expenses for members of the Armed Forces (not applicable) |
| 127 | - Line 18: Penalty on early withdrawal of savings |
| 128 | - Line 19a: Alimony paid (divorce agreements before 1/1/2019 only) |
| 129 | - Line 20: IRA deduction (from retirement skill if taxpayer made a traditional IRA contribution) |
| 130 | - Line 21: Student loan interest deduction (subject to income phase-out) |
| 131 | - Line 22: Reserved |
| 132 | - Line 23: Archer MSA deduction |
| 133 | - Line 24a-24z: Various other adjustments |
| 134 | - Line 25: Total other adjustments |
| 135 | |
| 136 | The orchestrator handles HSA, student loan interest, and other adjustments either itself (simple cases) or by refusing and flagging for the reviewer (complex cases). For v0.1, the orchestrator handles only the items flagged in the intake. |
| 137 | |
| 138 | ### Step 7: Compute AGI |
| 139 | |
| 140 | AGI (Form 1040 Line 11) = Total income (Line 9) − Adjustments from Schedule 1 Line 26. |
| 141 | |
| 142 | ### Step 8: Compute taxable income before QBI |
| 143 | |
| 144 | - Standard deduction for 2025: |
| 145 | - Single: $15,000 |
| 146 | - MFJ / QSS: $30,000 |
| 147 | - HoH: $22,500 |
| 148 | - MFS: $15,000 |
| 149 | - OR itemized deductions from Schedule A |
| 150 | - Taxable income before QBI = AGI − greater of standard or itemized |
| 151 | |
| 152 | ### Step 9: Run QBI skill |
| 153 | |
| 154 | Using the taxable income before QBI as the threshold test input. Produces QBI deduction for Form 1040 Line 13. Verify QBI self-checks pass. |
| 155 | |
| 156 | ### Step 10: Compute final taxable income |
| 157 | |
| 158 | Form 1040 Line 15 = Line 11 − Line 12 (standard/itemized) − Line 13 (QBI). |
| 159 | |
| 160 | ### Step 11: Compute tax |
| 161 | |
| 162 | Apply the 2025 tax brackets from Rev. Proc. 2024-40 to the final taxable income. Include: |
| 163 | - Regular income tax (using tax tables for income under $100K or tax rate schedules above) |
| 164 | - Capital gains tax (if applicable, from Schedule D) |
| 165 | - Other taxes (Schedule 2 Line 3) |
| 166 | |
| 167 | **2025 tax brackets (ordinary income):** |
| 168 | |
| 169 | Single: |
| 170 | - 10% on income up to $11,925 |
| 171 | - 12% on $11,925 to $48,475 |
| 172 | - 22% on $48,475 to $103,350 |
| 173 | - 24% on $103,350 to $197,300 |
| 174 | - 32% on $197,300 to $250,525 |
| 175 | - 35% on $250,525 to $626,350 |
| 176 | - 37% over $626,350 |
| 177 | |
| 178 | MFJ: |
| 179 | - 10% on income up to $23,850 |
| 180 | - 12% on $23,850 to $96,950 |
| 181 | - 22% on $96,950 to $206,700 |
| 182 | - 24% on $206,700 to $394,600 |
| 183 | - 32% on $394,600 to $501,050 |
| 184 | - 35% on $501,050 to $751,600 |
| 185 | - 37% over $751,600 |
| 186 | |
| 187 | HoH: |
| 188 | - 10% on income up to $17,000 |
| 189 | - 12% on $17,000 to $64,850 |
| 190 | - 22% on $64,850 to $103,350 |
| 191 | - 24% on $103,350 to $197,300 |
| 192 | - 32% on $197,300 to $250,500 |
| 193 | - 35% on $250,500 to $626,350 |
| 194 | - 37% over $626,350 |
| 195 | |
| 196 | **Source:** Rev. Proc. 2024-40 §3.01. |
| 197 | |
| 198 | ### Step 12: Compute Schedule 2 (additional taxes) |
| 199 | |
| 200 | Schedule 2 Line 4: SE tax from Schedule SE |
| 201 | Schedule 2 Line 2: Excess advance PTC repayment (from SE health insurance skill) |
| 202 | Schedule 2 Line 11: Additional Medicare Tax (Form 8959) if applicable |
| 203 | Schedule 2 Line 12: Net Investment Income Tax (Form 8960) if applicable |
| 204 | Schedule 2 Line 21: Total other taxes |
| 205 | |
| 206 | **Additional Medicare Tax thresholds (2025):** |
| 207 | - Single / HoH: $200,000 |
| 208 | - MFJ: $250,000 |
| 209 | - MFS: $125,000 |
| 210 | |
| 211 | Tax = 0.9% × (wages + SE earnings − threshold) |
| 212 | |
| 213 | **NIIT thresholds (2025):** Same as Additional Medicare Tax. Tax = 3.8% × (net investment income, capped at MAGI − threshold). Generally doesn't apply to pure freelance Schedule C income because Schedule C earnings are not "net investment income" — they're earned income. But if the taxpayer has meaningful investment income, NIIT may apply. |
| 214 | |
| 215 | ### Step 13: Compute Schedule 3 (credits and payments) |
| 216 | |
| 217 | Schedule 3 Line 1: Foreign tax credit (refusal if material — refer to base) |
| 218 | Schedule 3 Line 2: Child and dependent care expenses credit |
| 219 | Schedule 3 Line 3: Education credits (Form 8863) |
| 220 | Schedule 3 Line 4: Retirement savings contributions credit (Saver's credit, subject to income limits) |
| 221 | Schedule 3 Line 6: Other nonrefundable credits |
| 222 | Schedule 3 Line 9: Net premium tax credit (from Form 8962 if net PTC is refundable) |
| 223 | Schedule 3 Line 10: Amount paid with extension request (Form 4868) |
| 224 | Schedule 3 Line 11: Excess social security and tier 1 RRTA tax withheld |
| 225 | |
| 226 | ### Step 14: Compute total tax and payments |
| 227 | |
| 228 | - Form 1040 Line 22: Subtract Schedule 3 nonrefundable credits |
| 229 | - Form 1040 Line 23: Other taxes (from Schedule 2) |
| 230 | - Form 1040 Line 24: Total tax |
| 231 | - Form 1040 Line 25: Federal income tax withheld (from W-2s, 1099s) |
| 232 | - Form 1040 Line 26: 2024 estimated tax payments and amount applied from prior year |
| 233 | - Form 1040 Line 27: Earned income credit (generally not applicable for freelance developers above poverty line) |
| 234 | - Form 1040 Line 28: Additional child tax credit |
| 235 | - Form 1040 Line 29: Refundable American opportunity credit |
| 236 | - Form 1040 Line 31: Amount from Schedule 3 Line 15 (refundable credits) |
| 237 | - Form 1040 Line 33: Total payments |
| 238 | |
| 239 | ### Step 15: Compute refund or balance due |
| 240 | |
| 241 | - If Line 33 > Line 24: Refund (Line 34) |
| 242 | - If Line 33 < Line 24: Balance due (Line 37) |
| 243 | |
| 244 | ### Step 16: Run estimated tax skill for Form 2210 and 2026 planning |
| 245 | |
| 246 | Using the final total tax (Line 24), compute Form 2210 penalty if any installments were underpaid. Also compute 2026 quarterly installments for prospective planning. |
| 247 | |
| 248 | ### Step 17: Cross-form reconciliation checks |
| 249 | |
| 250 | See Section 4. |
| 251 | |
| 252 | ### Step 18: Produce the reviewer package |
| 253 | |
| 254 | See Section 5. |
| 255 | |
| 256 | --- |
| 257 | |
| 258 | ## Section 4 — Cross-form reconciliation checks |
| 259 | |
| 260 | The orchestrator verifies that amounts match between forms before producing output. Any mismatch is a hard error that stops assembly. |
| 261 | |
| 262 | **Check A: Schedule C Line 31 matches Schedule SE Line 2.** If they don't match, one of the skills has a bug. |
| 263 | |
| 264 | **Check B: Schedule SE Line 13 (deductible half of SE tax) matches Schedule 1 Line 15.** Same as above. |
| 265 | |
| 266 | **Check C: Form 8995/8995-A QBI deduction matches Form 1040 Line 13.** Same. |
| 267 | |
| 268 | **Check D: Schedule 1 total (Line 26) equals sum of Lines 11-25.** Arithmetic check. |
| 269 | |
| 270 | **Check E: Form 1040 Line 9 equals sum of Line 1a + Line 2b + Line 3b + Line 4b + Line 5b + Line 6b + Line 7 + Line 8 (from Schedule 1 Line 10).** Arithmetic. |
| 271 | |
| 272 | **Check F: Form 1040 Line 11 (AGI) = Line 9 − Line 10.** Arithmetic. |
| 273 | |
| 274 | **Check G: Form 1040 Line 15 (taxable income) = Line 11 − Line 12 − Line 13, but not less than zero.** Arithmetic. |
| 275 | |
| 276 | **Check H: Form 1040 Line 24 (total tax) = Line 22 + Line 23.** Arithmetic. |
| 277 | |
| 278 | **Check I: QBI used correct "taxable income before QBI."** The amount on Form 8995 Line 11 / Form 8995-A Line 34 should equal Form 1040 Line 11 minus Line 12 (standard or itemized deduction), before subtracting Line 13 (QBI). |
| 279 | |
| 280 | **Check J: Form 8962 reconciliation matches Schedule 2 Line 2 (repayment) or Schedule 3 Line 9 (net PTC).** Marketplace coverage. |
| 281 | |
| 282 | **Check K: If Form 2210 is filed, the penalty matches Form 1040 Line 38.** |
| 283 | |
| 284 | **Check L: Schedule 2 Line 4 (SE tax) equals Schedule SE Line 12.** |
| 285 | |
| 286 | **Check M: Total payments on Form 1040 Line 33 equals sum of Lines 25a-25c + 26 + 27 + 28 + 29 + 31.** |
| 287 | |
| 288 | **Check N: Form 1040 Line 34 (refund) or Line 37 (amount you owe) = Line 33 − Line 24. Exactly one of these is positive.** |
| 289 | |
| 290 | If any check fails, the orchestrator halts and escalates. The reviewer must be informed that assembly could not complete. |
| 291 | |
| 292 | --- |
| 293 | |
| 294 | ## Section 5 — Reviewer package output |
| 295 | |
| 296 | The orchestrator produces these artifacts: |
| 297 | |
| 298 | ### Excel builder pattern (CRITICAL — read before building the workbook) |
| 299 | |
| 300 | The Alex Chen test run revealed a failure mode: building the Excel workbook by inlining cell references (e.g., `='Sch C'!B45`) leads to row-reference collisions when content is added or reordered. The first-pass builder hit multiple bugs where formulas pointed at the wrong rows because the layout shifted as sheets were filled in. The second-pass fix required scrapping the first builder and starting over. |
| 301 | |
| 302 | **The pattern that works:** |
| 303 | |
| 304 | 1. **Build a single Python dict of every anchor cell BEFORE writing any formula.** The dict maps human-readable keys to cell coordinates: |
| 305 | ```python |
| 306 | anchors = { |
| 307 | 'sch_c.line_31_net_profit': None, # filled in when row is written |
| 308 | 'sch_se.line_12_se_tax': None, |
| 309 | 'sch_1.line_15_half_se_tax': None, |
| 310 | 'sch_1.line_16_retirement': None, |
| 311 | 'sch_1.line_17_se_health': None, |
| 312 | 'form_1040.line_11_agi': None, |
| 313 | 'form_1040.line_13_qbi': None, |
| 314 | 'form_1040.line_15_taxable_income': None, |
| 315 | # ... every anchor the workbook will reference |
| 316 | } |
| 317 | ``` |
| 318 | |
| 319 | 2. **Write sheets in dependency order** (Schedule C first, then SE, then Schedule 1, then QBI, then Form 1040). As you write each row, record the actual cell coordinate in the anchors dict: |
| 320 | ```python |
| 321 | row = 42 |
| 322 | ws['A' + str(row)] = 'Line 31 — Net profit' |
| 323 | ws['B' + str(row)] = '=B27-B40' # whatever the formula is |
| 324 | anchors['sch_c.line_31_net_profit'] = f"'Sch C'!B{row}" |
| 325 | ``` |
| 326 | |
| 327 | 3. **Only use anchors when writing cross-sheet formulas:** |
| 328 | ```python |
| 329 | # GOOD |
| 330 | ws['B15'] = f"={anchors['sch_c.line_31_net_profit']}" |
| 331 | |
| 332 | # BAD |
| 333 | ws['B15'] = "='Sch C'!B45" # will break if Sch C layout changes |
| 334 | ``` |
| 335 | |
| 336 | 4. **Assert every anchor is filled before writing cross-sheet formulas.** Run a check like: |
| 337 | ```python |
| 338 | missing = [k for k, v in anchors.items() if v is None] |
| 339 | assert not missing, f"Missing anchors: {missing}" |
| 340 | ``` |
| 341 | |
| 342 | 5. **After building, run openpyxl's formula verification** by opening the file with `data_only=False`, iterating every formula cell, and confirming no `#REF!` or `#NAME?` errors. |
| 343 | |
| 344 | 6. **Verify computed values against the Python model.** The orchestrator has already computed every number in Python. Before shipping the workbook, open it with `data_only=True` (or use libreoffice headless recalc) and compare key cells (net profit, AGI, total tax, balance due) against the Python numbers. Mismatches greater than $1 are bugs — investigate and fix before shipping. |
| 345 | |
| 346 | **Why this matters:** Excel workbooks that claim to be the authoritative computation but contain formula bugs are worse than no workbook. A reviewer who trusts the workbook and finds errors loses confidence in the entire package. Get the workbook right or don't ship it. |
| 347 | |
| 348 | **If you run out of context mid-workbook build:** ship a simplified flat-value workbook (just the final numbers, no cross-sheet formulas) with a note in the reviewer brief that "the live-formula working paper was not completed due to execution constraints; numbers are final but not interactively recomputable." Flat values with an honest note beat broken formulas. |
| 349 | |
| 350 | ### Artifact 1: Excel working paper (`[taxpayer]_2025_federal_working_paper.xlsx`) |
| 351 | |
| 352 | Sheets: |
| 353 | - **Summary** — Form 1040 line-by-line in spreadsheet form, with cell references to supporting sheets |
| 354 | - **Schedule C** — line by line, with references to transaction classifications |
| 355 | - **Schedule SE** — line by line |
| 356 | - **Schedule 1** — line by line |
| 357 | - **Schedule 2** — line by line |
| 358 | - **Schedule 3** — line by line (if used) |
| 359 | - **Form 8829** — home office (if claimed) |
| 360 | - **Form 4562** — depreciation (if claimed) |
| 361 | - **Form 8995 or 8995-A** — QBI |
| 362 | - **Form 8962** — PTC reconciliation (if marketplace coverage) |
| 363 | - **Form 2210** — underpayment penalty (if any) |
| 364 | - **Form 7206** — SE health insurance worksheet |
| 365 | - **Downstream items** — Schedule 1 Lines 15/16/17 used as inputs |
| 366 | - **Transactions** — the raw classified transaction list from bookkeeping |
| 367 | |
| 368 | ### Artifact 2: Reviewer brief (`[taxpayer]_2025_reviewer_brief.md`) |
| 369 | |
| 370 | Sections: |
| 371 | 1. **Taxpayer summary** — name, filing status, scope confirmation, refusals triggered (none if assembly completed) |
| 372 | 2. **Schedule C summary** — gross receipts, major expense categories, net profit |
| 373 | 3. **SE tax** — net SE earnings, SE tax, deductible half |
| 374 | 4. **Retirement contributions** — plan type, amount, Schedule 1 Line 16 |
| 375 | 5. **SE health insurance** — coverage type, eligible months, PTC interaction if any, Schedule 1 Line 17 |
| 376 | 6. **QBI deduction** — SSTB determination, threshold test, form used, deduction amount |
| 377 | 7. **Tax computation** — taxable income, regular tax, SE tax, other taxes, total tax |
| 378 | 8. **Payments and refund/balance due** |
| 379 | 9. **Form 2210 penalty** — if applicable |
| 380 | 10. **2026 estimated tax plan** — recommended quarterly installments |
| 381 | 11. **Open questions for reviewer** — any flags that need reviewer judgment |
| 382 | 12. **Citations** — primary sources for every significant position |
| 383 | |
| 384 | ### Artifact 3: Form package (PDF or fillable PDFs) |
| 385 | |
| 386 | For v0.1, the orchestrator produces a structured JSON representation of every form line, and flags that PDF rendering is a separate downstream step (handled by a future rendering module, not by this skill). |
| 387 | |
| 388 | ### Artifact 4: Form 1040-ES vouchers for 2026 |
| 389 | |
| 390 | Four quarterly vouchers with the recommended installment amounts, due dates, and payment instructions. |
| 391 | |
| 392 | --- |
| 393 | |
| 394 | ## Section 6 — Refusals specific to orchestration |
| 395 | |
| 396 | **R-ASSY-1 — Cross-form reconciliation failure.** If any reconciliation check in Section 4 fails, halt assembly and produce a diagnostic report. "Assembly failed: Schedule C Line 31 does not match Schedule SE Line 2. Upstream skill output is inconsistent. Reviewer must investigate before proceeding." |
| 397 | |
| 398 | **R-ASSY-2 — Upstream skill did not produce expected output.** If any content skill failed its self-checks, the orchestrator does not proceed. "Upstream skill [name] failed self-check [N]. Assembly cannot proceed until the upstream issue is resolved." |
| 399 | |
| 400 | **R-ASSY-3 — Taxpayer has income or deduction types not handled by any content skill.** Examples: royalties, schedule E income, rental income, K-1 from a partnership, capital gains from crypto. Halt assembly and refuse. |
| 401 | |
| 402 | **R-ASSY-4 — Total tax calculation produces negative or nonsensical result.** "Total tax computed as [value], which is not plausible. Assembly halted for reviewer investigation." |
| 403 | |
| 404 | **R-ASSY-5 — Required information still missing after intake.** "The following information is still missing: [list]. Assembly halted." |
| 405 | |
| 406 | --- |
| 407 | |
| 408 | ## Section 7 — Self-checks |
| 409 | |
| 410 | **Check 79 — All upstream content skills completed successfully.** Each content skill's self-checks passed and produced its expected output. |
| 411 | |
| 412 | **Check 80 — All reconciliation checks (A through N) passed.** |
| 413 | |
| 414 | **Check 81 — No refusals fired during assembly.** |
| 415 | |
| 416 | **Check 82 — Working paper has all expected sheets.** |
| 417 | |
| 418 | **Check 83 — Reviewer brief covers all required sections.** |
| 419 | |
| 420 | **Check 84 — All tax amounts are rounded consistently (to whole dollars, per IRS convention).** |
| 421 | |
| 422 | **Check 85 — Primary source citations present for every significant position.** |
| 423 | |
| 424 | **Check 86 — Reviewer identified and reviewer attention flags are listed.** |
| 425 | |
| 426 | **Check 87 — 2026 estimated tax vouchers produced if taxpayer has a 2026 obligation.** |
| 427 | |
| 428 | **Check 88 — CA state skill handoff data prepared (if taxpayer is CA resident).** The federal return produces certain numbers that the CA return needs (federal AGI, QBI deduction amount for add-back, etc.). This skill prepares those as a handoff package. |
| 429 | |
| 430 | --- |
| 431 | |
| 432 | ## Section 8 — Handoff to state skills |
| 433 | |
| 434 | If the taxpayer is a California resident, this skill produces a handoff package containing: |
| 435 | |
| 436 | - Federal AGI (Form 1040 Line 11) → CA Schedule CA (540) Part I Line 11 |
| 437 | - Federal QBI deduction → CA Schedule CA (540) add-back |
| 438 | - Federal §179 deduction and bonus depreciation → CA Schedule CA (540) add-back (California decouples) |
| 439 | - Federal Schedule C net profit → CA Schedule CA Part I |
| 440 | - Federal Schedule SE → CA does not have SE tax at state level, but AGI reconciliation needs this |
| 441 | - Federal Schedule 1 Line 17 (SE health insurance) → CA conforms; no adjustment |
| 442 | - Federal Schedule 1 Line 16 (retirement) → CA conforms; no adjustment |
| 443 | - Federal Form 8962 (PTC) → CA uses its own state subsidy computation if Covered California |
| 444 | - Federal estimated tax payments → flag for CA 540-ES comparison |
| 445 | |
| 446 | This handoff is consumed by the `ca-540-individual-return` skill. |
| 447 | |
| 448 | --- |
| 449 | |
| 450 | ## Section 9 — Reference material |
| 451 | |
| 452 | ### Known gaps |
| 453 | 1. **PDF rendering is not implemented.** The orchestrator produces JSON and Excel; PDF generation requires a separate rendering module. |
| 454 | 2. **E-file submission is not handled.** The reviewer uses a separate e-file provider after review. |
| 455 | 3. **Amended returns (Form 1040-X) are out of scope.** Only original returns. |
| 456 | 4. **Estimated tax payment tracking across the year** (separate from the return itself) is not handled — the taxpayer must manually track and report what was paid when. |
| 457 | 5. **The orchestrator assumes all upstream skills produce output in a consistent JSON-like schema.** Schema versioning is a v0.2 concern. |
| 458 | |
| 459 | ### Change log |
| 460 | - **v0.1 (April 2026):** Initial draft for freelance software developer product. |
| 461 | |
| 462 | ## End of US Federal Return Assembly Skill v0.1 |
| 463 |
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
12/12
About
Orchestrator that assembles the complete federal income tax return package from all upstream content skills.
USty-2025