/tc — Technical Change Tracker

Track every code change with structured JSON records and accessible HTML output. Ensures AI bot sessions can resume seamlessly when previous sessions expire or are abandoned. Designed for deployment across multiple projects.

First-Use Detection (MANDATORY — Every Session)

At the start of EVERY session, before doing any work:

1. Check if

   docs/TC/tc_config.json

   exists in the current working directory
2. If it EXISTS: follow the Session Start Protocol in the

   /tc resume

   section
3. If it does NOT exist: prompt the user:

   TC tracking is not initialized in this project. Would you like to set it up? This enables structured change tracking, AI session handoff, and HTML documentation. Run

   /tc init

   to get started.

4. Wait for the user's response. If they agree, run

   /tc init

   .
5. If the user declines, continue without TC tracking for this session.

A global skill is installed at

~/.claude/skills/tc.md

Overview

Each Technical Change (TC) is a structured record that documents:

• What changed (files, code, configuration)
• Why it changed (motivation, scope, design decisions)
• Who changed it (human or AI bot session)
• When it changed (revision history with timestamps)
• How it was tested (test cases with evidence from logs)
• Where work stands (session handoff data for bot continuity)

Storage Location

Each project stores TCs at

{project_root}/docs/TC/

docs/TC/
├── tc_config.json          # Project settings
├── tc_registry.json        # Master index
├── index.html              # Dashboard
├── records/
│   └── TC-001-MM-DD-YY-name/
│       ├── tc_record.json  # System of record
│       └── tc_record.html  # Human-readable
└── evidence/
    └── TC-001/             # Log snippets, screenshots

TC Naming Convention

• Parent TC:

  TC-NNN-MM-DD-YY-functionality-slug

  (e.g.,

  TC-001-04-03-26-user-authentication

  )
• Sub-TC:

  TC-NNN.A

  or

  TC-NNN.A.1

  (letter = revision, number = sub-revision)
• NNN = sequential number, MM-DD-YY = creation date, slug = kebab-case functionality name

Implementation States

planned → in_progress → implemented → tested → deployed
   │           │              │           │         │
   └→ blocked ←┘              └→ in_progress ←──────┘
   │    │  │                     (rework/hotfix)
   │    │  └→ paused → in_progress
   │    │       │
   │    └──────→└→ voided (terminal — cancelled)
   └→ voided

• paused: Development work temporarily stopped. Can resume to

  in_progress

  or cancel to

  voided

  .
• voided: TC cancelled entirely. Terminal state — cannot transition out.

Commands

/tc init

Initialize TC tracking in the current project. Run this once per project.

Steps:

1. Check if

   docs/TC/tc_config.json

   exists. If yes, report "Already initialized" with current stats and stop.
2. Detect project name: try CLAUDE.md first heading, then package.json name, then pyproject.toml name, then directory basename. Confirm with user.
3. Create directories:

   docs/TC/

   ,

   docs/TC/records/

   ,

   docs/TC/evidence/

4. Create

   tc_config.json

   :

   {
     "project_name": "<detected>",
     "tc_root": "docs/TC",
     "created": "<ISO 8601 now>",
     "skills_library_path": "<absolute path to skills_library/TC>",
     "auto_track": true,
     "auto_regenerate_html": true,
     "auto_regenerate_dashboard": true,
     "default_author": "Claude",
     "categories": ["feature","bugfix","refactor","infrastructure","documentation","hotfix","enhancement"]
   }
   

5. Create

   tc_registry.json

   :

   {
     "project_name": "<name>",
     "created": "<ISO 8601>",
     "updated": "<ISO 8601>",
     "next_tc_number": 1,
     "records": [],
     "statistics": {
       "total": 0,
       "by_status": {"planned":0,"in_progress":0,"blocked":0,"implemented":0,"tested":0,"deployed":0,"paused":0,"voided":0},
       "by_scope": {"feature":0,"bugfix":0,"refactor":0,"infrastructure":0,"documentation":0,"hotfix":0,"enhancement":0},
       "by_priority": {"critical":0,"high":0,"medium":0,"low":0}
     }
   }
   

6. Generate empty dashboard: run

   python "<skills_path>/generators/generate_dashboard.py" "docs/TC/tc_registry.json"

7. Update CLAUDE.md: read existing file (or create new). Check for marker

   ## Technical Change (TC) Tracking (MANDATORY)

   . If not found, append the contents of

   init/claude_md_snippet.md

   with

   {skills_library_path}

   replaced with the actual absolute path.
8. Update

   .claude/settings.local.json

   : read existing file (or create

   {"permissions":{"allow":[]}}

   ). Merge TC permissions from

   init/settings_template.json

   (with paths substituted). Deduplicate. Write back.
9. Report all created/updated files. Suggest

   /tc create

   as next step.

/tc create <functionality-name>

Create a new TC record.

Steps:

1. Read

   docs/TC/tc_registry.json

2. Generate TC ID:

   TC-{next_tc_number:03d}-{MM-DD-YY}-{slugify(name)}

3. Ask user for:
   • Title (default: formatted version of the slug)
   • Scope: feature, bugfix, refactor, infrastructure, documentation, hotfix, enhancement
   • Priority: critical, high, medium, low (default: medium)
   • Summary (at least 10 characters)
   • Motivation (why is this change needed?)
4. Create directory:

   docs/TC/records/TC-NNN-MM-DD-YY-slug/

5. Create

   tc_record.json

   with all fields initialized:
   • status = "planned"
   • revision_history = [R1 creation event]
   • session_context.current_session populated with this session's info
   • All arrays initialized to []
   • approval.approved = false, test_coverage_status = "none"
6. Add entry to tc_registry.json records array. Increment next_tc_number. Recompute statistics.
7. Generate HTML: run the tc_record HTML generator
8. Regenerate dashboard: run the dashboard generator
9. Report: display TC ID, link to HTML, suggest next steps

/tc update <tc-id>

Update an existing TC record. This is the general-purpose update command.

Steps:

1. Read the TC record from

   docs/TC/records/<tc-dir>/tc_record.json

2. Determine what to update (user may specify, or you determine from context):
   • Status change: validate transition with state machine. Ask for reason.
   • Add files: append to files_affected array
   • Add test case: create new test entry with sequential ID (T1, T2...)
   • Update test result: set actual_result, status, evidence, tested_by, tested_date
   • Add evidence: append to a test case's evidence array
   • Update handoff: update session_context.handoff fields
   • Add notes: append to notes field
   • Add sub-TC: append to sub_tcs array
3. For EVERY change:
   • Append a new revision entry to revision_history (sequential R-id, timestamp, author, summary, field_changes with old/new values and reason)
   • Update the

     updated

     timestamp
   • Update

     metadata.last_modified

     and

     metadata.last_modified_by

   • Update

     session_context.current_session.last_active

4. Write tc_record.json (atomic: write to .tmp, then rename)
5. Update tc_registry.json (sync status, scope, priority, updated, test_summary). Recompute statistics.
6. If auto_regenerate_html: regenerate TC HTML
7. If status changed and auto_regenerate_dashboard: regenerate dashboard

/tc status [tc-id]

View TC status.

Without tc-id: Read tc_registry.json and display a summary table of all TCs:

• TC ID, Title, Status (with badge), Scope, Priority, Tests (pass/total), Last Updated

With tc-id: Read the specific TC record and display:

• Full status including handoff data, test results, revision count, files affected
• Any validation errors

/tc resume <tc-id>

Resume work on a TC from a previous session.

Steps:

1. Read the TC record
2. Display the handoff section prominently:
   • Progress summary
   • Next steps (numbered)
   • Blockers (highlighted)
   • Key context
   • Files in progress with their states
   • Recent decisions
3. Archive the current session to session_history:
   • Move current_session data to a new entry in session_history
   • Set ended = now
4. Create new current_session with this session's info
5. Append revision entry: "Session resumed by [platform/model]"
6. Write tc_record.json
7. Prompt: "Ready to continue. Here are the next steps: [list from handoff]"

/tc close <tc-id>

Close a TC by transitioning it to deployed.

Steps:

1. Read the TC record
2. Validate current status allows transition to

   deployed

3. Check all test cases — warn if any are pending/fail/blocked
4. Ask for:
   • Approval: who is approving? (user name or "self")
   • Approval notes (optional)
   • Final test coverage assessment (none/partial/full)
5. Update:
   • status = "deployed"
   • approval.approved = true
   • approval.approved_by, approved_date, approval_notes, test_coverage_status
   • Append final revision entry
   • Archive session to session_history
6. Write tc_record.json and update registry
7. Regenerate HTML and dashboard
8. Report: "TC-NNN closed and deployed."

/tc export

Regenerate ALL HTML files from their JSON records.

Steps:

1. Read tc_registry.json
2. For each record: run the TC HTML generator on its tc_record.json
3. Run the dashboard generator
4. Report: "Regenerated X TC pages and dashboard."

/tc dashboard

Regenerate just the dashboard index.html.

Steps:

1. Run the dashboard generator on tc_registry.json
2. Report path to generated index.html

/tc retro <retro_changelog.json>

Retroactively create TC records in bulk from a structured changelog file. Use this when onboarding an existing project with extensive undocumented history.

Steps:

1. Read the retro_changelog.json file (must match

   schemas/tc_retro_changelog.schema.json

   )
2. Validate the changelog structure
3. Run the batch generator:

   python "{skills_library_path}/generators/generate_retro_tcs.py" "<retro_changelog.json>" "docs/TC"
   

4. The generator will:
   • Create a TC record for each entry (TC-001 through TC-NNN)
   • Validate every record against the schema
   • Generate HTML for every record
   • Update the registry with all entries
   • Regenerate the dashboard
5. Report: total created, any errors, link to dashboard

Retro Changelog Format (

retro_changelog.json

{
  "project": "Project Name",
  "default_author": "retroactive",
  "changes": [
    {
      "title": "Feature or Change Title",
      "scope": "feature|bugfix|refactor|infrastructure|documentation|hotfix|enhancement",
      "priority": "critical|high|medium|low",
      "status": "deployed",
      "date": "YYYY-MM-DD",
      "description": "What changed and why (10+ chars)",
      "motivation": "Why this change was needed (optional)",
      "files": ["path/to/file.py", "path/to/other.py"],
      "tags": ["tag1", "tag2"],
      "version": "v1.0.0"
    }
  ]
}

Building the changelog: Claude should analyze the project's git history, docs, changelogs, README, and code to build the retro_changelog.json. Group related changes into single TCs. Each TC should represent one logical unit of work (a feature, a fix, a refactor).

/tc retro --from-git

Auto-generate the retro_changelog.json directly from git history instead of building it manually.

Steps:

1. Run the git-to-changelog generator:

   python "{skills_library_path}/generators/generate_retro_from_git.py" \
     --repo-path "." \
     --output "retro_changelog.json" \
     --project-name "Project Name" \
     --since "2024-01-01" \
     --until "2026-04-05"
   

2. The generator will:
   • Parse

     git log

     to extract all commits with files changed, dates, authors, messages
   • Group related commits into logical TCs using:
     • Merge commit / PR boundaries (primary, if the repo uses merge/squash workflow)
     • File-overlap clustering (commits touching the same files)
     • Time-proximity grouping (same author, within ~2 hour window)
   • Auto-detect scope from commit messages: "fix" -> bugfix, "feat" -> feature, "refactor" -> refactor, "docs" -> documentation, "chore"/"ci" -> infrastructure
   • Auto-detect priority: default medium, "critical"/"urgent"/"hotfix" -> critical/high
   • Write a valid

     retro_changelog.json

     matching

     schemas/tc_retro_changelog.schema.json

3. Review the generated changelog (optional but recommended — edit titles, adjust scopes/priorities)
4. Feed it into the batch TC generator:

   python "{skills_library_path}/generators/generate_retro_tcs.py" "retro_changelog.json" "docs/TC"
   

5. Report: total TCs created, link to dashboard

CLI Options:

--repo-path PATH

.

--output PATH

retro_changelog.json

--project-name NAME

--since DATE

--until DATE

--author NAME

retroactive

--time-window HOURS

2

/tc link <tc-id> [<sha>|HEAD|--range A..B]

Link git commits to a TC record. Appends to

git.commits[]

files_affected[]

Steps:

1. Resolve the SHA (default: HEAD). For

   --range

   , resolve all commits in the range.
2. For each commit: read metadata via

   git show

   , skip if SHA already linked (dedup).
3. Append to

   git.commits[]

   with

   link_source: "manual"

   .
4. Merge

   files_changed

   into

   files_affected[]

   (skip duplicates).
5. Append revision history entry: "Linked N commit(s)".
6. Regenerate TC HTML.

/tc git status

Show the git integration state of all TC records.

Output:

• Unlinked TCs: Records with no

  git

  block (candidates for

  /tc link

  )
• Linked TCs: Records with

  git.commits[]

  populated (with commit count)
• Online-enriched TCs: Records with PR metadata
• Unlinked commits: Recent commits on the current branch not linked to any TC
• Uncommitted files: Matching

  files_affected[]

  of in-progress TCs

/tc pr link <tc-id> [<pr-number>]

(Online opt-in) Link a PR/MR to a TC record. Requires

gh

glab

Steps:

1. Auto-detect provider from

   git remote -v

   .
2. If no PR number given, find PR for current branch via

   gh pr view <branch>

   .
3. Populate

   git.remotes[].pr

   with number, URL, state, review decision, merge commit.
4. Append revision entry. Regenerate TC HTML.
5. Graceful degradation: if CLI is missing or unauthenticated, report and exit cleanly.

/tc sync [<tc-id>|--all]

(Online opt-in) Refresh PR metadata for TCs with linked PRs.

Steps:

1. For each TC with

   git.remotes[].pr.number

   populated:
   • Query current PR state via

     gh pr view

     or

     glab mr view

     .
   • Update state, review_decision, merged_sha, last_synced.
2. If PR state changed, append revision entry.
3. Report: "Updated N TC(s)" or "No changes (offline or up-to-date)".

/tc git install-merge-driver

Register the TC registry merge driver to handle

tc_registry.json

Steps:

1. Run:

   git config merge.tc-registry.driver 'python "<path>/tc_registry_merge.py" %O %A %B'

2. Add to

   .gitattributes

   :

   docs/TC/tc_registry.json merge=tc-registry

3. Report: "Merge driver registered."

Auto-Detection Rules — Non-Blocking Subagent Pattern

TC tracking MUST NOT interrupt the main workflow. Use background subagents for all bookkeeping.

During Work

• NEVER stop to update TC records inline. Focus entirely on the task.
• Do not read/write TC files between code changes.
• The main agent's job is to code, not to do paperwork.

At Natural Milestones

When a logical unit of work is complete (feature done, test passing, stopping point):

• Spawn a background Agent (run_in_background=true) with this prompt: "Read docs/TC/tc_registry.json. Find the in_progress TC. Read its tc_record.json. Update files_affected with [list files changed]. Append a revision entry summarizing what was done. Update session_context.current_session.last_active. Write the updated record. Regenerate the TC HTML and dashboard."
• The main agent continues working without waiting.

Only Surface Questions When Genuinely Needed

• "This work doesn't match any active TC — should I create one?" (ask once per session, not per file)
• "TC-NNN looks complete — transition to implemented?" (at milestones only, don't nag)
• Never interrupt the user for routine TC bookkeeping.

At Session End

Before the session closes, spawn a final background Agent to write the handoff summary:

• progress_summary: what was accomplished
• next_steps: what still needs doing
• blockers: anything preventing progress
• key_context: important decisions, gotchas, patterns the next bot needs
• files_in_progress: which files are mid-edit

On Session Start

1. Check if

   docs/TC/

   exists in the project
2. If yes: read tc_registry.json, find in_progress/blocked TCs
3. Display handoff summary for any active TCs
4. Ask user if they want to resume

Validation Rules (Always Enforced)

1. State machine: only valid transitions allowed (see diagram above)
2. Sequential IDs: revision_history uses R1,R2,R3...; test_cases uses T1,T2,T3...
3. Append-only history: revision_history entries are never modified or deleted
4. Approval consistency: approved=true requires approved_by and approved_date
5. TC ID format: must match

   TC-NNN-MM-DD-YY-slug

   pattern
6. Sub-TC ID format: must match

   TC-NNN.A

   or

   TC-NNN.A.N

   pattern
7. HTML escaping: all user data is escaped before HTML rendering
8. Atomic writes: JSON files written to .tmp then renamed
9. Registry stats: recomputed on every registry write

Python Generators

Located at

{skills_library_path}/generators/

# Generate individual TC HTML
python "generators/generate_tc_html.py" "<path_to_tc_record.json>" [--output <path>]

# Generate dashboard
python "generators/generate_dashboard.py" "<path_to_tc_registry.json>" [--output <path>]

# Validate a TC record
python "validators/validate_tc.py" "<path_to_tc_record.json>"

# Validate the registry
python "validators/validate_tc.py" --registry "<path_to_tc_registry.json>"

# Retroactive batch creation
python "generators/generate_retro_tcs.py" "<retro_changelog.json>" "<docs/TC/>"

# Generate retro_changelog.json from git history
python "generators/generate_retro_from_git.py" [--repo-path .] [--output retro_changelog.json] [--project-name "Name"] [--since 2024-01-01] [--until 2026-04-05]

# --- Git Integration ---

# Link commit(s) to a TC record
python "generators/tc_git_link.py" "<tc_record.json>" [<sha>|HEAD] [--range A..B]

# Show git integration status for all TCs (finds unlinked TCs + unlinked commits)
python "generators/tc_git_status.py" "<docs/TC/>" [--unlinked-only] [--show-candidates]

# Auto-link HEAD to the single in-progress TC (used by PostToolUse hook)
python "generators/tc_git_autolink.py" --if-commit [<docs/TC/>]

# Pre-commit advisory: warn if staged files aren't in any active TC (used by PreToolUse hook)
python "generators/tc_precommit_check.py" --if-commit [<docs/TC/>]

# Registry 3-way merge driver (register with git config for conflict resolution)
python "generators/tc_registry_merge.py" <base> <ours> <theirs>

# --- Online (opt-in) ---

# Link a PR/MR to a TC record (requires gh or glab CLI)
python "generators/tc_pr_link.py" "<tc_record.json>" [<pr_number>]

# Refresh PR metadata for all TCs with linked PRs
python "generators/tc_sync.py" "<docs/TC/>" [<tc_id>]

# --- Session Lifecycle ---

# Display session start report with active TC handoff data
python "generators/tc_session_start.py" "<docs/TC/>" [--json]

# Archive current session and write handoff data
python "generators/tc_session_end.py" "<tc_record.json>" [--summary "..."] [--next "..."]

All generators use Python stdlib only — no external dependencies. All generators validate their input before producing output. All HTML output is self-contained with inlined CSS (works from file:// URLs). All HTML output is WCAG AA+ accessible with rem-based fonts, high contrast dark theme, skip links, and aria labels.