claude-skills-reference/commands/tc.md

name: tc description: Track technical changes with structured records, a state machine, and session handoff. Usage: /tc <init|create|update|status|resume|close|export|dashboard> [args]

/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

1. Run:

   python3 engineering/tc-tracker/scripts/tc_init.py --root . --json
   

2. If status is already_initialized, report current statistics and stop.
3. Otherwise report what was created and suggest /tc create <name> as the next step.

create <name>

1. Parse <name> as a kebab-case slug. If missing, ask the user for one.
2. 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
3. Run:

   python3 engineering/tc-tracker/scripts/tc_create.py --root . \
     --name "<slug>" --title "<title>" --scope <scope> --priority <priority> \
     --summary "<summary>" --motivation "<motivation>" --json
   

4. Report the new TC ID and the path to the record.

update <tc-id> [intent]

1. If <tc-id> is missing, list active TCs (status in_progress or blocked) from tc_status.py --all and ask which one.
2. 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>
3. Run:

   python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json
   

4. 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]

• If <tc-id> is provided:

  python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>
  

• Otherwise:

  python3 engineering/tc-tracker/scripts/tc_status.py --root . --all
  

resume <tc-id>

1. Run:

   python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json
   

2. Display the handoff block prominently: progress_summary, next_steps (numbered), blockers, key_context.
3. Ask: "Resume and pick up at next step 1? (y/n)"
4. 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"
   

5. Begin executing the first item in next_steps. Do NOT re-derive context — trust the handoff.

close <tc-id>

1. Read the record via tc_status.py --tc-id <tc-id> --json.
2. Verify the current status is tested. If not, refuse and tell the user which transitions are still required.
3. Check test_cases: warn if any are pending, fail, or blocked.
4. Ask the user:
   • "Who is approving? (your name, or 'self')"
   • "Approval notes (optional):"
   • "Test coverage status: none / partial / full"
5. 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.
6. Report: "TC-NNN closed and deployed."

export

There is no automatic HTML export in this skill. Re-validate everything instead:

1. Read the registry.
2. For each record, run:

   python3 engineering/tc-tracker/scripts/tc_validator.py --record <path> --json
   

3. Run:

   python3 engineering/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json
   

4. 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

1. Never edit tc_record.json by hand. Always use tc_update.py so revision history is appended and validation runs.
2. Never skip the state machine. Walk forward through states even if it feels redundant.
3. Never delete a TC. History is append-only — add a final revision and tag it [CANCELLED].
4. Background bookkeeping. When mid-task, spawn a background subagent to update the TC. Do not pause coding to do paperwork.
5. 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.