tc-tracker

---
name: tc-tracker
description: Use when the user asks to track technical changes, create change records, manage a change's lifecycle, or hand off in-progress work between AI sessions.
category: Engineering
version: 1.0.0
tools: []
---

# TC Tracker

Track every code change with structured records, an enforced state machine, and a session handoff format that lets a new AI session resume work cleanly when a previous one expires.

## Overview

A Technical Change (TC) is a structured record that captures **what** changed, **why** it changed, **who** changed it, **when** it changed, **how it was tested**, and **where work stands** for the next session. Treat each TC as a JSON-shaped record you compose and maintain in the chat/Knowledge Base rather than a file — validated against a strict schema and a state machine.

**Use this when the user:**
- Asks to "track this change" or wants an audit trail for code modifications
- Wants to hand off in-progress work to a future AI session
- Needs structured release notes that go beyond commit messages
- Onboards an existing project and wants retroactive change documentation
- Asks to init, create, update, check status of, resume, or close a TC

**Do NOT use this when:**
- The user only wants a changelog from git history — that's release-notes generation, a different job
- The user only wants to track tech debt items — that's a debt registry, not a change record
- The change is trivial (typo, formatting) and won't affect behavior

## TC ID Convention

- **Parent TC:** `TC-NNN-MM-DD-YY-functionality-slug` (e.g., `TC-001-04-05-26-user-authentication`)
- **Sub-TC:** `TC-NNN.A` or `TC-NNN.A.1` (letter = revision, digit = sub-revision)
- `NNN` is sequential, `MM-DD-YY` is the creation date, slug is kebab-case.

## State Machine

```
planned -> in_progress -> implemented -> tested -> deployed
   |            |              |           |          |
   +-> blocked -+              +- in_progress <-------+
        |                          (rework / hotfix)
        +-> planned
```

Only these transitions are legal. "Just set status to deployed" from `planned` is not a valid transition — walk through `in_progress -> implemented -> tested -> deployed` even under time pressure, because skipping steps hides skipped phases from the audit trail.

## Record Contents

Every TC record holds: an ID following the convention above; title, scope (feature/fix/refactor/etc.), priority; a summary and motivation; a `revision_history` of sequential `R1, R2, R3...` entries, each appended (never edited or deleted) on every change, with a reason and timestamp; a list of files touched with their change type (`created`, `modified`, `deleted`); `test_cases` numbered sequentially `T1, T2, T3...`; an `approval` block where `approved=true` requires both `approved_by` and `approved_date` together; and the `session_context.handoff` block described below.

## Session Handoff Format

The handoff block is the single most important field for AI continuity across sessions. It contains: `progress_summary` (what has been done); `next_steps` (an ordered list of remaining actions, kept current — stale next_steps defeats the entire purpose of handoff); `blockers` (anything preventing progress); `key_context` (critical decisions, gotchas, patterns the next session must know); `files_in_progress` (files being edited and their state — `editing`, `needs_review`, `partially_done`, `ready`); and `decisions_made` (architectural decisions with rationale and timestamp).

## Validation Rules (Always Enforced)

1. **State machine** — only valid transitions are allowed.
2. **Sequential IDs** — revision history uses `R1, R2, R3...`; test cases use `T1, T2, T3...`.
3. **Append-only history** — revision entries are never modified or deleted; corrections are new revisions.
4. **Approval consistency** — `approved=true` requires `approved_by` and `approved_date`.
5. **TC ID format** — must match `TC-NNN-MM-DD-YY-slug`; sub-TCs match `TC-NNN.A` or `TC-NNN.A.N`.
6. **Registry stats** — recomputed whenever the record set changes.

## Non-Blocking Bookkeeping Pattern

TC tracking must NOT interrupt the main workflow. Never stop mid-task to update a TC record inline — keep coding, and update the record at natural milestones instead. Surface questions only when genuinely needed ("this work doesn't match any active TC — create one?"), and ask once per session, not per file. At session end, always write a final handoff block before closing, even if it's just "nothing changed since last update."

## Retroactive Bulk Creation

For onboarding an existing project with undocumented history, build a list of logical changes (one entry per feature or fix, grouped by intent — not by file) and create one TC per entry. Group commits by feature, not by file, or the registry explodes into noise.

## Anti-Patterns

| Anti-pattern | Why it's bad | Do this instead |
|--------------|--------------|-----------------|
| Editing `revision_history` to "fix" a typo | History is append-only — tampering destroys the audit trail | Add a new revision that corrects the field |
| Skipping the state machine ("just set status to deployed") | Bypasses validation and hides skipped phases | Walk through the full chain of transitions |
| Creating one TC per file changed | Fragments related work and explodes the registry | One TC per logical unit (feature, fix, refactor) |
| Updating TC inline between every code edit | Slows the main agent, wastes context | Update at milestones only |
| Marking `approved=true` without `approved_by` | Misleading audit trail | Always set `approved_by` and `approved_date` together |
| Putting secrets in notes or evidence | Records may be shared or persisted | Reference an env var or external secret store instead |
| Reusing TC IDs after deletion | Breaks the sequential guarantee and confuses history | Increment forward only — never recycle |
| Letting `next_steps` go stale | Defeats the purpose of handoff | Update on every milestone, even if it's "nothing changed" |

## Adjacent Expertise

For user-facing release notes generated from commit history, or for tracking long-lived tech-debt items rather than discrete changes, or for a systematic multi-phase bug-fix process, or for promoting an architectural decision to a project-wide decision log, or for pre-merge code review — @mention a teammate with that specialty; TC tracker owns the granular per-change audit trail and AI-session handoff, not those adjacent jobs.