From super-tax-agent
Analyze comparison diffs, classify discrepancies, and generate fixes to skill files and references. Logs patterns to evolution-log.json and invokes tax-publish when fixes are ready. Use after running tax-compare.
How this skill is triggered — by the user, by Claude, or both
Slash command
/super-tax-agent:tax-evolveThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Analyze discrepancies found by `/tax-compare`, classify root causes, generate fixes to skill files and references, and submit improvements as a GitHub PR.
Analyze discrepancies found by /tax-compare, classify root causes, generate fixes to skill files and references, and submit improvements as a GitHub PR.
data/comparison-{year}.json must exist. If not, tell the user to run /tax-compare first.data/tax-calculation.json must exist (for tax year context).NEVER include user PII in any generated file changes. This means:
evolution-log.json, store only line numbers, deltas, and classification — never raw values that could identify a taxpayer.Read data/comparison-{year}.json. Identify all entries with status: "mismatch" or status: "missing_ours". If there are no mismatches, tell the user:
"Great news — no discrepancies found! No fixes needed." And stop.
For each mismatch, classify it into one of three categories by reasoning about the line:
calculation_error — The interview collected the right data, but the formula in tax-calculate or its references (brackets-2025.md, credits-2025.md) produced the wrong result.
skills/tax-calculate/SKILL.md or the relevant reference file.missing_data — The interview did not ask a question needed to correctly compute this line.
missing_ours (zero in our return, non-zero in reference) for a deduction or credit the user is entitled to.skills/tax-start/SKILL.md.missing_domain — The discrepancy involves an income or deduction type that has no dedicated domain skill yet (e.g., Schedule C self-employment, HSA, student loan interest).
tax-domain-* skill scaffold.Document the classification for each mismatch before proceeding to fixes.
Read data/evolution-log.json (create it if it does not exist with {"entries": []}).
Look for lines that have appeared as mismatches in previous runs (same line field). If any line has appeared 2 or more times:
"Line {N} ({description}) has appeared as a mismatch in {count} previous runs. This suggests a systemic gap — proposing a domain skill scaffold rather than a one-off fix."
Upgrade the classification of repeat offenders to missing_domain if appropriate.
For each classified discrepancy, generate the actual file changes. Do NOT write files yet — collect all proposed changes first.
calculation_error:Grep to find the relevant calculation step in skills/tax-calculate/SKILL.md.skills/tax-calculate/references/credits-2025.md for credit phase-out rules.skills/tax-calculate/references/brackets-2025.md for bracket amounts.CTC = number_of_qualifying_children * 2000 (no phase-out applied)CTC = number_of_qualifying_children * 2000, reduced by $50 for each $1,000 of MAGI above $400,000 (MFJ) / $200,000 (other)Edit operation for the relevant file.missing_data:tax-start interview would logically include the missing question.Edit operation for skills/tax-start/SKILL.md.missing_domain:---
name: tax-domain-{name}
description: [domain] tax rules. Invoked by core skills when [trigger].
allowed-tools: [Read, Write, Edit, AskUserQuestion]
---
## Trigger Conditions
## Interview Questions
## Data Schema
## Calculation Rules
## References
Write operations for skills/tax-domain-{name}/SKILL.md and an empty skills/tax-domain-{name}/references/ placeholder.Before writing any files, present all proposed changes for review:
Proposed fixes for 3 discrepancies:
============================================================
1. [calculation_error] Line 19 — Child Tax Credit
File: skills/tax-calculate/references/credits-2025.md
Change: Add MAGI phase-out rule for CTC above $200,000/$400,000
2. [missing_data] Line 26 — Estimated Tax Payments
File: skills/tax-start/SKILL.md
Change: Add question about estimated quarterly tax payments
3. [missing_domain] Line 17 — Rental Income (Schedule E)
New file: skills/tax-domain-rental/SKILL.md
Change: New domain skill scaffold for rental property income
============================================================
Proceed with these changes? (yes/no/review <n>)
Apply only the changes the user approved. Use Edit for modifications to existing files, Write for new files.
After applying changes, run a quick sanity check:
ls skills/tax-calculate/references/
ls skills/tax-start/SKILL.md
Append an entry to data/evolution-log.json:
{
"date": "2026-04-02",
"comparisonFile": "data/comparison-2025.json",
"lines": [
{
"line": "19",
"description": "Child tax credit",
"deltaDirection": "under",
"deltaPercent": 17.6,
"classification": "calculation_error",
"resolved": true,
"fixFile": "skills/tax-calculate/references/credits-2025.md"
}
]
}
Fields to include per line entry:
line — 1040 line number (string, e.g., "19")description — human-readable descriptiondeltaDirection — "over" (our value higher) or "under" (our value lower)deltaPercent — absolute percentage difference, e.g., 17.6 for 17.6% offclassification — one of calculation_error, missing_data, missing_domainresolved — true if a fix was applied this run, false if skippedfixFile — the file that was changed (if resolved), else nullDo NOT store actual dollar amounts in the log.
If at least one fix was applied, tell the user:
"Fixes applied. Ready to submit as a GitHub PR. Invoking
/tax-publish..."
Then invoke /tax-publish evolve-{year}-fixes.
If no fixes were applied (user declined all), say:
"No changes were applied. You can run
/tax-evolveagain after reviewing the comparison data."
data/comparison-{year}.json is missing or has no mismatch entries, tell the user and stop.data/evolution-log.json is corrupted, create a fresh one with {"entries": []} and warn the user.skills/tax-calculate/references/credits-2025.md), tell the user which file needs to be created first and stop.npx claudepluginhub fangyi-chen/tax-marketplace --plugin super-tax-agentEvolves SKILL.md files from agent execution traces using a three-stage pipeline: trajectory collection, parallel multi-agent patch proposal, and conflict-free consolidation.
Analyzes skill outcome logs and user corrections, then proposes self-improvements to skill behavior and description hygiene.
Analyzes skill executions from conversation friction, file diffs, user feedback, diagnostics, and lessons to propose concrete improvements to SKILL.md files for efficiency.