/tc

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/skills/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/skills/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/skills/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/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>

• Otherwise:

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

`resume <tc-id>`

1. Run:

   python3 engineering/skills/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 <tc-id> and pick up at next step 1? (y/n)" 4. If yes, run an update to record the resumption:

   python3 engineering/skills/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/skills/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/skills/tc-tracker/scripts/tc_validator.py --record <path> --json

3. Run:

   python3 engineering/skills/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/skills/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