/tc — Technical Change Tracker
Dispatch a TC (Technical Change) command. Arguments: $ARGUMENTS.
If $ARGUMENTS is empty, print this menu and stop:
/tc init Initialize TC tracking in this project
/tc create <name> Create a new TC record
/tc update <tc-id> [...] Update fields, status, files, handoff
/tc status [tc-id] Show one TC or the registry summary
/tc resume <tc-id> Resume a TC from a previous session
/tc close <tc-id> Transition a TC to deployed
/tc export Re-render derived artifacts
/tc dashboard Re-render the registry summary
Otherwise, parse $ARGUMENTS as <subcommand> <rest> and dispatch to the matching protocol below. All scripts live at engineering/tc-tracker/scripts/.
Subcommands
init
- Run:
python3 engineering/tc-tracker/scripts/tc_init.py --root . --json
- If status is
already_initialized, report current statistics and stop.
- Otherwise report what was created and suggest
/tc create <name> as the next step.
create <name>
- Parse
<name> as a kebab-case slug. If missing, ask the user for one.
- Prompt the user (one question at a time) for:
- Title (5-120 chars)
- Scope:
feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement
- Priority:
critical | high | medium | low (default medium)
- Summary (10+ chars)
- Motivation
- Run:
python3 engineering/tc-tracker/scripts/tc_create.py --root . \
--name "<slug>" --title "<title>" --scope <scope> --priority <priority> \
--summary "<summary>" --motivation "<motivation>" --json
- Report the new TC ID and the path to the record.
update <tc-id> [intent]
- If
<tc-id> is missing, list active TCs (status in_progress or blocked) from tc_status.py --all and ask which one.
- Determine the user's intent from natural language:
- Status change →
--set-status <state> with --reason "<why>"
- Add files → one or more
--add-file path[:action]
- Add a test →
--add-test "<title>" --test-procedure "<step>" --test-expected "<result>"
- Update handoff → any combination of
--handoff-progress, --handoff-next, --handoff-blocker, --handoff-context
- Add a note →
--note "<text>"
- Add a tag →
--tag <tag>
- Run:
python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json
- If exit code is non-zero, surface the error verbatim. The state machine and validator will reject invalid moves — do not retry blindly.
status [tc-id]
resume <tc-id>
- Run:
python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json
- Display the handoff block prominently:
progress_summary, next_steps (numbered), blockers, key_context.
- Ask: "Resume and pick up at next step 1? (y/n)"
- If yes, run an update to record the resumption:
python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
--note "Session resumed" --reason "session handoff"
- Begin executing the first item in
next_steps. Do NOT re-derive context — trust the handoff.
close <tc-id>
- Read the record via
tc_status.py --tc-id <tc-id> --json.
- Verify the current status is
tested. If not, refuse and tell the user which transitions are still required.
- Check
test_cases: warn if any are pending, fail, or blocked.
- Ask the user:
- "Who is approving? (your name, or 'self')"
- "Approval notes (optional):"
- "Test coverage status: none / partial / full"
- Run:
python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
--set-status deployed --reason "Approved by <approver>" --note "Approval: <approver> — <notes>"
Then directly edit the approval block via a follow-up update if your script version supports it; otherwise instruct the user to record approval in notes.
- Report: "TC-NNN closed and deployed."
export
There is no automatic HTML export in this skill. Re-validate everything instead:
- Read the registry.
- For each record, run:
python3 engineering/tc-tracker/scripts/tc_validator.py --record <path> --json
- Run:
python3 engineering/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json
- Report: total records validated, any errors, paths to anything invalid.
dashboard
Run the all-records summary:
python3 engineering/tc-tracker/scripts/tc_status.py --root . --all
Iron Rules
- Never edit
tc_record.json by hand. Always use tc_update.py so revision history is appended and validation runs.
- Never skip the state machine. Walk forward through states even if it feels redundant.
- Never delete a TC. History is append-only — add a final revision and tag it
[CANCELLED].
- Background bookkeeping. When mid-task, spawn a background subagent to update the TC. Do not pause coding to do paperwork.
- Validate before reporting success. If a script exits non-zero, surface the error and stop.
Related Skills
engineering/tc-tracker — Full SKILL.md with schema reference, lifecycle diagrams, and the handoff format.
engineering/changelog-generator — Pair with TC tracker: TCs for the per-change audit trail, changelog for user-facing release notes.
engineering/tech-debt-tracker — For tracking long-lived debt rather than discrete code changes.
1---2name: skills-tc3description: "Track technical changes with structured records, a state machine, and session handoff. Usage: /tc <init|create|update|status|resume|close|export|dashboard> [args]"4metadata:5 source: https://skillmd.com/skills/zuoguyoupan2023/skills-tc6---78# /tc — Technical Change Tracker910Dispatch a TC (Technical Change) command. Arguments: `$ARGUMENTS`.1112If `$ARGUMENTS` is empty, print this menu and stop:1314```15/tc init Initialize TC tracking in this project16/tc create <name> Create a new TC record17/tc update <tc-id> [...] Update fields, status, files, handoff18/tc status [tc-id] Show one TC or the registry summary19/tc resume <tc-id> Resume a TC from a previous session20/tc close <tc-id> Transition a TC to deployed21/tc export Re-render derived artifacts22/tc dashboard Re-render the registry summary23```2425Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the matching protocol below. All scripts live at `engineering/tc-tracker/scripts/`.2627## Subcommands2829### `init`30311. Run:32 ```bash33 python3 engineering/tc-tracker/scripts/tc_init.py --root . --json34 ```352. If status is `already_initialized`, report current statistics and stop.363. Otherwise report what was created and suggest `/tc create <name>` as the next step.3738### `create <name>`39401. Parse `<name>` as a kebab-case slug. If missing, ask the user for one.412. Prompt the user (one question at a time) for:42 - Title (5-120 chars)43 - Scope: `feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement`44 - Priority: `critical | high | medium | low` (default `medium`)45 - Summary (10+ chars)46 - Motivation473. Run:48 ```bash49 python3 engineering/tc-tracker/scripts/tc_create.py --root . \50 --name "<slug>" --title "<title>" --scope <scope> --priority <priority> \51 --summary "<summary>" --motivation "<motivation>" --json52 ```534. Report the new TC ID and the path to the record.5455### `update <tc-id> [intent]`56571. If `<tc-id>` is missing, list active TCs (status `in_progress` or `blocked`) from `tc_status.py --all` and ask which one.582. Determine the user's intent from natural language:59 - **Status change** → `--set-status <state>` with `--reason "<why>"`60 - **Add files** → one or more `--add-file path[:action]`61 - **Add a test** → `--add-test "<title>" --test-procedure "<step>" --test-expected "<result>"`62 - **Update handoff** → any combination of `--handoff-progress`, `--handoff-next`, `--handoff-blocker`, `--handoff-context`63 - **Add a note** → `--note "<text>"`64 - **Add a tag** → `--tag <tag>`653. Run:66 ```bash67 python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json68 ```694. If exit code is non-zero, surface the error verbatim. The state machine and validator will reject invalid moves — do not retry blindly.7071### `status [tc-id]`7273- If `<tc-id>` is provided:74 ```bash75 python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>76 ```77- Otherwise:78 ```bash79 python3 engineering/tc-tracker/scripts/tc_status.py --root . --all80 ```8182### `resume <tc-id>`83841. Run:85 ```bash86 python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json87 ```882. Display the handoff block prominently: `progress_summary`, `next_steps` (numbered), `blockers`, `key_context`.893. Ask: "Resume <tc-id> and pick up at next step 1? (y/n)"904. If yes, run an update to record the resumption:91 ```bash92 python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \93 --note "Session resumed" --reason "session handoff"94 ```955. Begin executing the first item in `next_steps`. Do NOT re-derive context — trust the handoff.9697### `close <tc-id>`98991. Read the record via `tc_status.py --tc-id <tc-id> --json`.1002. Verify the current status is `tested`. If not, refuse and tell the user which transitions are still required.1013. Check `test_cases`: warn if any are `pending`, `fail`, or `blocked`.1024. Ask the user:103 - "Who is approving? (your name, or 'self')"104 - "Approval notes (optional):"105 - "Test coverage status: none / partial / full"1065. Run:107 ```bash108 python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \109 --set-status deployed --reason "Approved by <approver>" --note "Approval: <approver> — <notes>"110 ```111 Then directly edit the `approval` block via a follow-up update if your script version supports it; otherwise instruct the user to record approval in `notes`.1126. Report: "TC-NNN closed and deployed."113114### `export`115116There is no automatic HTML export in this skill. Re-validate everything instead:1171181. Read the registry.1192. For each record, run:120 ```bash121 python3 engineering/tc-tracker/scripts/tc_validator.py --record <path> --json122 ```1233. Run:124 ```bash125 python3 engineering/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json126 ```1274. Report: total records validated, any errors, paths to anything invalid.128129### `dashboard`130131Run the all-records summary:132```bash133python3 engineering/tc-tracker/scripts/tc_status.py --root . --all134```135136## Iron Rules1371381. **Never edit `tc_record.json` by hand.** Always use `tc_update.py` so revision history is appended and validation runs.1392. **Never skip the state machine.** Walk forward through states even if it feels redundant.1403. **Never delete a TC.** History is append-only — add a final revision and tag it `[CANCELLED]`.1414. **Background bookkeeping.** When mid-task, spawn a background subagent to update the TC. Do not pause coding to do paperwork.1425. **Validate before reporting success.** If a script exits non-zero, surface the error and stop.143144## Related Skills145146- `engineering/tc-tracker` — Full SKILL.md with schema reference, lifecycle diagrams, and the handoff format.147- `engineering/changelog-generator` — Pair with TC tracker: TCs for the per-change audit trail, changelog for user-facing release notes.148- `engineering/tech-debt-tracker` — For tracking long-lived debt rather than discrete code changes.