Skip to content

/tc

Slash Command Source

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:
  3. Title (5-120 chars)
  4. Scope: feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement
  5. Priority: critical | high | medium | low (default medium)
  6. Summary (10+ chars)
  7. Motivation
  8. Run: 
    python3 engineering/tc-tracker/scripts/tc_create.py --root . \
  --name "<slug>" --title "<title>" --scope <scope> --priority <priority> \
  --summary "<summary>" --motivation "<motivation>" --json
  9. 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:
  3. Status change → --set-status <state> with --reason "<why>"
  4. Add files → one or more --add-file path[:action]
  5. Add a test → --add-test "<title>" --test-procedure "<step>" --test-expected "<result>"
  6. Update handoff → any combination of --handoff-progress, --handoff-next, --handoff-blocker, --handoff-context
  7. Add a note → --note "<text>"
  8. Add a tag → --tag <tag>
  9. Run: 
    python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json
  10. 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:
  5. "Who is approving? (your name, or 'self')"
  6. "Approval notes (optional):"
  7. "Test coverage status: none / partial / full"
  8. 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.
  9. 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.
  • 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.