alirezarezvani/claude-skills / engineering/skills/tc-tracker
tc-tracker
VerifiedUse when tracking technical changes as records, or handing work between AI sessions with a change record. Creates, updates and validates change records with tc_create.py, tc_update.py and tc_validator.py.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.2 KB |
| SKILL.md | skill md | 10.0 KB |
| references/handoff-format.md | markdown | 5.2 KB |
| references/lifecycle.md | markdown | 3.9 KB |
| references/tc-schema.md | markdown | 5.3 KB |
| scripts/tc_create.py | script | 9.7 KB |
| scripts/tc_init.py | script | 6.7 KB |
| scripts/tc_status.py | script | 7.2 KB |
| scripts/tc_update.py | script | 13.8 KB |
| scripts/tc_validator.py | script | 13.9 KB |
references/lifecycle.md
View on GitHub# TC Lifecycle and State Machine
A TC moves through six implementation states. Transitions are validated on every write — invalid moves are rejected with a clear error.
## State Diagram
```
+-----------+
| planned |
+-----------+
| ^
v |
+-------------+
+-----> | in_progress | <-----+
| +-------------+ |
| | | |
v | v |
+---------+ | +-------------+ |
| blocked |<---+ | implemented | |
+---------+ +-------------+ |
| | |
v v |
+---------+ +--------+ |
| planned | | tested |-----+
+---------+ +--------+
|
v
+----------+
| deployed |
+----------+
|
v
in_progress (rework / hotfix)
```
## Transition Table
| From | Allowed Transitions |
|------|---------------------|
| `planned` | `in_progress`, `blocked` |
| `in_progress` | `blocked`, `implemented` |
| `blocked` | `in_progress`, `planned` |
| `implemented` | `tested`, `in_progress` |
| `tested` | `deployed`, `in_progress` |
| `deployed` | `in_progress` |
Same-status transitions are no-ops and always allowed. Anything else is an error.
## State Definitions
| State | Meaning | Required Before Moving Forward |
|-------|---------|--------------------------------|
| `planned` | TC has been created with description and motivation | Decide implementation approach |
| `in_progress` | Active development | Code changes captured in `files_affected` |
| `blocked` | Cannot proceed (dependency, decision needed) | At least one entry in `handoff.blockers` |
| `implemented` | Code complete, awaiting tests | All target files in `files_affected` |
| `tested` | Test cases executed, results recorded | At least one `test_case` with status `pass` (or explicit `skip` with rationale) |
| `deployed` | Approved and shipped | `approval.approved=true` with `approved_by` and `approved_date` |
## Recovery Flows
### "I committed before testing"
1. Status is `implemented`.
2. Write tests, run them, set `test_cases[*].status = pass`.
3. Transition `implemented -> tested`.
### "Production bug in a deployed TC"
1. Open the deployed TC.
2. Transition `deployed -> in_progress`.
3. Add a new revision summarizing the rework.
4. Walk forward through `implemented -> tested -> deployed` again.
### "Blocked, then unblocked"
1. From `in_progress`, transition to `blocked`. Add blockers to `handoff.blockers`.
2. When unblocked, transition `blocked -> in_progress` and clear/move blockers to `notes`.
### "Cancelled work"
There is no `cancelled` state. If a TC is abandoned:
1. Add a final revision: "Cancelled — reason: ...".
2. Move to `blocked`.
3. Add a `[CANCELLED]` tag.
4. Leave the record in place — never delete it (history is append-only).
## Status Field Discipline
- Update `status` ONLY through `tc_update.py --set-status`. Never edit JSON by hand.
- Every status change creates a new revision entry with `field` = `status`, `action` = `changed`, and `reason` populated.
- The registry's `statistics.by_status` is recomputed on every write.
## Anti-patterns
| Anti-pattern | Why it's wrong |
|--------------|----------------|
| Skipping `tested` and going straight to `deployed` | Bypasses validation; misleads downstream consumers |
| Deleting a record to "cancel" a TC | History is append-only; deletion breaks the audit trail |
| Re-using a TC ID after deletion | Sequential numbering must be preserved |
| Changing status without a `--reason` | Future maintainers cannot reconstruct intent |
| Long-lived `in_progress` TCs (weeks+) | Either too big — split into sub-TCs — or stalled and should be marked `blocked` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |