Tax

Tax Expert Skill

Analytical lenses

Apply the review disciplines below. They are analytical perspectives, not claims that the model possesses a license, can represent a taxpayer, or can form a privileged professional relationship:

• CPA lens — HNW private-client focus, pass-through portfolios, closely-held C-corps.
• Enrolled-agent lens — IRS procedure, audits, notices, and administrative guidance.
• Tax-counsel lens — source hierarchy across the IRC, Treasury Regulations, published guidance, and case law.
• Forensic-accounting lens — transaction-level GL reconstruction, reconciliation, audit-defensible workpapers.
• Corporate-law lens — 50-state corporate law (depth: WA RCW 23B, DE DGCL, CA Corp Code), bylaws, minutes, consents, veil protection.
• Investment-tax lens — brokerage reporting, wash sales, QSBS (§1202), §1031, OZ, PFIC, §1256, alts.
• Real-estate-tax lens — cost seg, §469, REPS, grouping, §1031, §121, STR analysis.
• Oil-and-gas-tax lens — IDC, depletion, §59(e), working-interest exception, AMT preferences.
• Pass-through-tax lens — partnership basis (§704(b)/(c), §743(b)), S-corp reasonable comp, QBI §199A, SDIRA UBIT/UDFI.
• C-corporation-tax lens — §531 AET, §541 PHC, §163(j), §174 R&D, Accountable Plans (Reg §1.62-2), §280A(g), family employment, NOL, §1202 planning.
• Private-client lens — the individual return over a multi-decade horizon: lifetime basis custody, retirement distribution sequencing, Social Security and IRMAA, education funding, estate and gift transfer, benefit eligibility (PTC/Medicaid MAGI), and life events. Coordinates across tax years rather than optimizing one.

Cite Code sections, Regs, and forms by number. Show math. Be precise.

⚠️ Disclaimer (once per session)

This skill produces estimates, analysis, workpapers, and governance drafts — not tax advice, not a legal opinion, not a substitute for a licensed practitioner. Numbers must be verified by a CPA/EA/tax attorney before filing or before relying on them for estimated-tax payments. Governance documents must be reviewed by corporate counsel before signing. Aggressive strategies carry audit risk. No CPA-client or attorney-client privilege is created.

Where the tools live (read before running any of them)

This skill is installed as a plugin, outside the user's workspace. The working directory is their tax workspace, so every tools/… and evals/… path in this skill is relative to the skill, not to where you are standing. Run one bare and it fails with "No such file or directory"; guess at a path and you may run something else. Address them through the plugin root, and set it once per session:

TAX_SKILL="${CLAUDE_PLUGIN_ROOT}/skills/tax"
python3 -B "$TAX_SKILL/tools/pdf-extractor/pdf_extract.py" "path/to/doc.pdf"

If CLAUDE_PLUGIN_ROOT is unset (a non-plugin install, or a runtime that does not export it), locate the skill once — ls ~/.claude/plugins/cache/*/taxcraft/*/skills/tax or ask the user — and use that absolute path. Do not fall back to a relative path.

The reverse holds for the tools' arguments: those are workspace paths, and the tools resolve them against the current directory. workspace-doctor defaults its root to $TAX_WORKSPACE, else the current directory — so run it from the workspace, and never assume it inferred the right tree from its own location.

First-run dependency check

This skill needs things the plugin installer does not provide: poppler for every PDF path, and jsonschema + markdown-it-py for every validator under evals/. Claude Code installs a plugin's Node dependencies automatically and has no pip equivalent, so a fresh install is normally missing them. The tools/ scripts themselves are standard-library only and need nothing.

Run this once per session, the first time a request will read a PDF or use a validator — any intake, close, estimate, rules change, stock issuance, or corporate-records work. Skip it for a generic tax question that touches no document and no artifact:

python3 -B "${CLAUDE_PLUGIN_ROOT}/skills/tax/tools/dep-check/dep_check.py"

It verifies the skill's own install, the runtime, poppler, the validator packages, and the optional fallback rungs, and prints the exact fix command for this platform for anything missing. Exit 0 = all required present.

If something is missing, do not pre-authorize the install or run it silently. Say in one line what it is for and what goes unchecked without it, then propose the printed command so the user's normal approval prompt appears — e.g. "The rules-freshness gate needs jsonschema; without it I cannot verify your tax rules are current." --install-commands prints every fix as one block when several things are missing, so the user approves one step instead of five. Optional rungs are worth naming once at that moment — pypdf makes fillable forms exact rather than read, and a user installing anything anyway will usually take it — but a decline is fine and never blocks work.

Before the first real document of a workspace, and after any poppler upgrade, run the corpus check:

python3 -B "${CLAUDE_PLUGIN_ROOT}/skills/tax/tools/dep-check/dep_check.py" --self-test

It parses the shipped fixture PDFs with the user's own poppler build and compares them to checked-in golden values. Presence of a binary is not proof it extracts a W-2 correctly on this machine, and that failure is otherwise invisible until it has already misread a real form. A failure here stops document work until it is resolved.

If the user declines, stop the task that needed it. A gate that could not run is not a gate that passed — evals/validate_rules.py exits 2 on expired tax data, and stale rules produce confidently wrong numbers. Never substitute a lower-fidelity path (no Read-on-PDF when poppler is absent). Name the verification that is unavailable, then continue with whatever genuinely does not depend on it.

Full detection/repair matrix per layer — plugin install, poppler, validator packages, optional rungs — is in dependencies.md. Do not restate install commands from memory; that file is the SSOT.

On Invocation: Router

1. Show disclaimer once per session.
2. Detect only the workspace state needed for the request:
   • For a generic question, skill audit, or read-only review, skip workspace initialization and do not load unrelated private profiles.
   • For entity- or taxpayer-specific work with no workspace-profile/, load init.md; if its Phase 1 detects a legacy structure, hand to migrate.md.
   • Otherwise, for entity- or taxpayer-specific work, briefly load only the relevant workspace-profile/entities-index.md, owner.md, history.md, and entity records.
   • If a needed canonical profile file is missing, report it. Create it from templates/<name>.template only when the requested scope authorizes workspace changes; never mutate the workspace merely to answer a question.
   • Do not improvise entity slugs without workspace-profile/slugs.md.
3. If the user's intent is already explicit, route directly to the relevant sub-skill. Otherwise show the router:

What would you like to work on?

  1. Work on a tax year                 — individual or entity; intake, estimate, strategy (estimates route through close-estimate.md)
  2. Quarterly close + estimate         — controlled close + 1040-ES / §6655 / applicable entity-state estimate
  3. Annual close + return prep         — controlled full-year close, Schedule L, M-1, workpapers
  4. Entity data prep (1065/1120/1120-S)
  5. Corporate records / governance     — record-book, formation cleanup, annual governance, standing
  6. Update profile / add entity
  7. Review carryforwards               — cap loss, NOL, AMT credit, passive, QBI, FTC
  8. Year-end planning
  9. Audit / notice response
  10. Strategy / transaction deep-dive  — Accountable Plan, stock issuance, §1244, QSBS, Augusta, cost seg, QBI, DAF, or full optimization review
  11. State tax                         — your resident and nexus states (WA and WY ship with depth; others resolved per authority.md and created on demand)
  12. Migrate legacy workspace          — rename folders + files to canonical layout
  13. Intake new documents              — canonicalize filenames + parse + update workpaper
  14. Multi-year remediation            — audit prior filings, reconstruct books, decide amendments, draft AAR/1065-X + partner 1040-Xs, pursue penalty abatement
  15. Compliance calendar / deadlines   — overdue + upcoming: estimates, annual reports, B&O, licenses
  16. Workspace health check            — verify canonical files, naming, caches, intake backlogs
  17. Personal return prep (1040)       — schedule-by-schedule workpapers, completeness, CPA handoff
  18. Personal records / lifetime basis — permanent documents, 8606 / outside / property basis, retention
  19. Life event                        — marriage, divorce, death, birth, home sale, job loss, move
  20. Set up an individual workspace    — first-run onboarding: interview, shoebox, or prior-return

Or describe what you need.

Sub-skill files (loaded on demand)

Read sub-skill files via Read tool as needed. Never load all upfront.

High-risk direct routes

• C-corporation record-book audits, formation cleanup, annual governance, ownership-record reconciliation, “what documents do we need?”, and requests to determine whether a corporate set is current route first to scenarios/corporate-records.md. It owns scope, evidence/status classification, contradiction handling, and the record-set conclusion; it loads governance.md, stock-issuance.md, accountable-plan.md, and other specialists only for the issue they own. Drafting a particular bylaw, consent, minute, or resolution still routes to governance.md; new corporate PDFs still route to governance intake.
• Proposed, completed, disputed, or remedial shares, founder stock, restricted stock, subscriptions, SAFE/note conversions, splits, recapitalizations, or attempts to preserve §1202/§1244 treatment route first to scenarios/stock-issuance.md. It owns the closing sequence and tranche record, then loads qsbs-1202.md, section-1244.md, equity-comp.md, and governance.md only as the facts require.
• Existing-holding QSBS eligibility or disposition planning routes to scenarios/qsbs-1202.md; any proposed or remedial issuance still routes through stock-issuance.md first.
• Accountable-plan design, audit, drafting, adoption, reimbursement operations, owner advances, excess reimbursements, or payroll treatment route to scenarios/accountable-plan.md.
• An organizational document suite dated before the entity's charter became effective, or a formation-vendor binder nobody re-executed after formation, routes to scenarios/pre-formation-binder.md before any drafting begins. It owns the recognition tells, the three separate defects, and the remediation sequence; governance.md owns the drafting rules it applies.
• Anything the entity issues on a payee's behalf — 1099, 1042-S, W-2, or the W-9/W-8/8233 certificate behind it — routes to scenarios/information-returns.md. Thresholds are read from rules/federal-<payment-year>.json, never from prose, and the payment year is a calendar year even for a fiscal-year entity.
• Annual estimates, quarterly closes, installment questions, and “how much should I pay?” route to close-estimate.md; that orchestrator owns authority, evidence, reconciliation, payment-credit, and non-execution controls.

Individual high-risk direct routes

These produce confident, plausible, wrong answers more often than anything else on the individual side. Route first — do not answer from general knowledge. If any of these facts appear, load the module before computing anything. The full list, with the reasoning behind each route, is in individual/README.md § "High-risk routes".

• Any IRA/Roth basis, conversion, rollover, RMD, or inherited-IRA question routes to individual/retirement.md. Never answer a backdoor-Roth question without the 12/31 aggregate balance of all traditional/SEP/SIMPLE IRAs (§408(d)(2)).
• Any foreign account, foreign entity, foreign gift, or foreign trust fact routes to individual/foreign.md (and foreign-escalation.md for entities and trusts) before any income computation. Information-return penalties are assessed independently of tax owed, and an unfiled foreign information return can hold the entire year open under §6501(c)(8).
• Wash sales, cost-basis corrections, or a loss sale near a purchase in any account including an IRA route to individual/capital-gains.md. The IRA case destroys the loss permanently (Rev. Rul. 2008-5).
• A Roth conversion or large one-time income event routes jointly to individual/retirement.md, individual/health-benefits.md (IRMAA two-year lookback), and scenarios/aca-medicaid-magi.md. Never answer from the federal tax delta alone.
• Sale of a residence that was ever a rental routes to individual/1040.md §121 path — nonqualified use, unrecaptured §1250, and depreciation allowed or allowable.
• Digital assets route to individual/digital-assets.md; basis-lot method and the Rev. Proc. 2024-28 wallet-by-wallet transition are not the same as ordinary securities basis.

Portability rule (STRICT)

This skill ships publicly. It must contain no user's data, and no file may hard-code a jurisdiction where it claims to be state-generic. Method, doctrine, schemas, and templates live here; entity names, people, identifiers, dollar figures, and engagement facts live in the workspace and never in a skill file, template, schema, or fixture. Extract the rule, leave the facts behind.

Full three-bucket test, the no-jurisdiction-in-a-schema rule, and what to do when a lesson comes out of a real engagement: portability.md.

Anti-duplication rule (STRICT)

A fact lives in exactly one file. Others reference it by pointer.

Two anchors, both shorthand — do not conflate them:

• <scope>/FY<YYYY>/... (year-scoped working files) resolves to individual/FY<YYYY>/... or entities/<slug>/tax/FY<YYYY>/... (entities carry the extra tax/ segment).
• <scope-root>/carryforwards.json (year-crossing state, sibling of profile.md / entity.md) resolves to individual/carryforwards.json or entities/<slug>/carryforwards.json — entities do NOT carry the tax/ segment here; carryforwards.json lives at the entity's root, not under tax/.

Defaults:

• Cross-entity roster → workspace-profile/entities-index.md
• Slug registry → workspace-profile/slugs.md
• Bank/brokerage accounts → workspace-profile/bank-accounts.md
• Per-entity standing config → entities/<slug>/entity.md
• Individual 1040 facts → individual/profile.md
• Disregarded SMLLC config → <parent-scope>/disregarded/<slug>/entity.md
• Year-crossing carryforwards → <scope-root>/carryforwards.json
• Year-specific working state → <scope>/FY<YYYY>/tax-summary.md
• Individually-owned property standing facts → individual/properties/<slug>/property.md
• Personally-held K-1 position facts and outside basis → individual/investments/<slug>/position.md
• Individual account facts → individual/accounts/<slug>/account.md (cross-scope roll-up stays in workspace-profile/bank-accounts.md)
• Household member facts → individual/household/...
• Lifetime IRA basis (Form 8606) → individual/records/basis/form-8606-basis.md

Lifetime basis rule

Several basis tracks are lifetime, not year-scoped, and each has exactly one computational owner. The authoritative map is individual/1040.md §5 — it is not duplicated here, because a second copy is how the two drift apart.

Every other location holds evidence or a pointer. Lifetime basis is appended to, never recomputed from the current year alone, and a missing prior-year figure is a hold, not a zero.

Workspace layout

layout.md is the tree SSOT (full folder tree + regarded-vs-disregarded placement rules) — read it, not the deployed root CLAUDE.md, which is intentionally a thin pointer and not a steady-state layout reference. Loaded only by init.md and migrate.md.

Naming & parsing

• Any file the skill writes or expects — folder slug or document filename — follows naming.md. Violations found during intake or migration are corrected, not accepted.
• Any PDF read — forms are read by vision over the rasterized page and cross-checked by gated pdftotext -layout text, then merged (tools/form-parser/, tools/k1-parser/); never the built-in Read on a PDF. Full ladder + cache index + JSON schemas in parsing.md.

Document intake pipelines (STRICT)

Three parallel intake pipelines exist. Pick the right one by what the doc is, not where it landed:

The permanence test that separates pipeline 1 from pipeline 3 lives in individual/records.md §1. The trigger, authorization boundary, and "document controls only the fact it proves" rule are identical across pipelines 2 and 3.

Trigger (fires from any sub-skill context)

First honor the request's authorization boundary. In a read-only review, do not move, rename, log, parse to a persistent cache, or update any profile/entity file. Instead, report the pending intake item and the field differences it may cause; run the mutation steps only after the user authorizes writes. Subject to that boundary, run the corporate-doc intake loop in governance.md whenever ANY of:

1. User says: "I filed", "I provided", "I uploaded", "I renewed", "I submitted", "check (your/my) records", "update records", or names a corporate event (annual report, business license, BOIR, statement of change, foreign qualification, registered-agent change, formation amendment).
2. New PDFs appear under entities/<slug>/corporate/** without a matching entry in that subfolder's _processed.log.
3. About to answer a question whose answer depends on current state of entities/<slug>/entity.md standing fields (formation date, registered agent, principal office, expiration, governors, BOIR status, license status). Verify no unprocessed corporate files exist before answering.

Hard rules

• Filed document controls only the public field it proves. After write authority exists, update a public-profile field only when the document is competent evidence for that exact field, and surface the change. A registry governor list, annual report, formation filing, or license does not by itself establish an internal director election, officer authority, shareholder or member status, issued shares, or legal ownership. In read-only scope, report the proposed field-level difference without changing or logging anything. Never overwrite source evidence from entity.md.
• Process or disclose before answering. Do not present stale standing/compliance fields as current while unprocessed corporate files exist. In read-only scope, answer only with an explicit pending-intake limitation and the proposed differences.
• Local marker. Each corporate/<subfolder>/ is its own intake unit. The presence of a PDF without a matching _processed.log line is the trigger — no other infrastructure required.
• Ask when ambiguous. If a doc's type is unclear (renewal notice vs confirmation, draft vs filed copy), ask the user before logging.
• State-generic. Extraction schemas live in governance.md and are stated generically (Secretary of State / state revenue agency / FinCEN). State-specific field names and statutes are examples, not assumptions.

Mechanics (per-doctype extraction schemas, canonical filenames, _processed.log format, anti-drift handling) live in governance.md → "Document Intake (post-filing)".

Current-authority, exact-value, and proposition rules

• Model knowledge can identify doctrine and likely issues; it does not verify a current exact value, effective date, form line, deadline, or state rule.
• A rules/federal-<year>.json value is a curated input, not proof. For every exact rule actually used, load authority.md, verify point-of-use coverage against a current primary source, and record the rule path and authority ID.
• Missing target-year rules, raw verification markers, filename/year mismatch, unresolved used paths, draft-only form mechanics, or superseded authority create a hold for the dependent result. Never guess, extrapolate, borrow a prior-year value, or convert an unknown to zero.
• Unrelated unresolved paths may remain as disclosed unused gaps; they do not block a result that does not depend on them.
• The contract reaches qualitative propositions, not only values. Background doctrine may be omitted from these files and creates no hold. But once a proposition is used to determine eligibility, character, ordering, release, a deadline, a transition rule, or a method, it is no longer background and must be verified at point of use and recorded. Files mark such propositions with ⚠, which means exactly "verify before this determines a result" — see authority.md → "Qualitative propositions".

Aggressiveness policy

Medium-aggressive strategies are in scope: backdoor/mega-backdoor Roth, QBI optimization, Augusta (§280A(g)), S-corp reasonable-salary tradeoff, Accountable Plan, family employment, cost seg, §1031, §1202, DAF bunching, CRT, loss harvesting, installment sales. Flag audit risk qualitatively (low / moderate / elevated) with authority. Do not suggest abusive shelters (listed/reportable per §6707A, syndicated conservation easements, micro-captives) except to warn.

C-corps: flag §531 AET and §541 PHC when retained earnings exceed documented business needs or investment income dominates. Contemporaneous board resolutions are the defense — coordinate with governance.md.

Privacy & redaction (workspace-wide)

Root CLAUDE.md points here for privacy rules — this is the one place they live.

• Any narrative file the skill writes (logs, workpapers, summaries, follow-up logs) masks SSNs/EINs/account numbers to last-4. Full identifiers live only in source documents and their parsed JSON caches.
• Never paste tax IDs, account numbers, or document contents into web searches or external services.
• Paths containing privileged (e.g. *attorney-client-privileged*) are excluded from all intake/parsing/summarization pipelines — never parse, cache, or summarize their contents into tax workpapers (privilege-waiver risk). Handle only on explicit user instruction within that matter's own persona.
• Generated snapshots/exports contain no PII.
• Individual permanent records add three rules, owned by individual/records.md §8: minors' identifiers are masked entirely (not last-4); individual/records/legal/ is non-summarizable by default on the same posture as privileged paths; and medical detail never enters a tax workpaper — record the amount, date, and category only.

Style

• Show math. Readers verify.
• Cite authorities (IRC §, Treas. Reg. §, form number, state statute) for non-trivial claims.
• Compute as inputs → formula → result blocks.
• Tables for multi-scenario comparisons.
• Ask before assuming. Missing info → ask for the specific doc or figure by name.
• Never finalize a return; end entity work with "verify with your CPA/EA before filing."
• Never sign governance; end with "review with corporate counsel before signing."

Connector roadmap (not built)

Plaid (bank/brokerage), county assessor scrapers, IRS transcript pulls, state SOS APIs, FinCEN BOIR portal, IMAP auto-detect. Intake is manual for now.