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/handoff-format.md
View on GitHub# Session Handoff Format
The handoff block is the most important part of a TC for AI continuity. When a session expires, the next session reads this block to resume work cleanly without re-deriving context.
## Where it lives
`session_context.handoff` inside `tc_record.json`.
## Structure
```json
{
"progress_summary": "string",
"next_steps": ["string", "..."],
"blockers": ["string", "..."],
"key_context": ["string", "..."],
"files_in_progress": [
{
"path": "src/foo.py",
"state": "editing|needs_review|partially_done|ready",
"notes": "string|null"
}
],
"decisions_made": [
{
"decision": "string",
"rationale": "string",
"timestamp": "ISO 8601"
}
]
}
```
## Field-by-field rules
### `progress_summary` (string)
A 1-3 sentence narrative of what has been done. Past tense. Concrete.
GOOD:
> "Implemented JWT signing with HS256, wired the auth middleware into the main router, and added two passing unit tests for the happy path."
BAD:
> "Working on auth." (too vague)
> "Wrote a bunch of code." (no specifics)
### `next_steps` (array of strings)
Ordered list of remaining actions. Each step should be small enough to complete in 5-15 minutes. Use imperative mood.
GOOD:
- "Add integration test for invalid token (401)"
- "Update README with the new POST /login endpoint"
- "Run `pytest tests/auth/` and capture output as evidence T2"
BAD:
- "Finish the feature" (not actionable)
- "Make it better" (no measurable outcome)
### `blockers` (array of strings)
Things preventing progress RIGHT NOW. If empty, the TC should not be in `blocked` status.
GOOD:
- "Test fixtures for the user model do not exist; need to create `tests/fixtures/user.py`"
- "Waiting for product to confirm whether refresh tokens are in scope (asked in #product channel)"
BAD:
- "It's hard." (not a blocker)
- "I'm tired." (not a blocker)
### `key_context` (array of strings)
Critical decisions, gotchas, patterns, or constraints the next session MUST know. Things that took the current session significant effort to discover.
GOOD:
- "The `legacy_auth` module is being phased out — do NOT extend it. New code goes in `src/auth/`."
- "We use HS256 (not RS256) because the secret rotation tooling does not support asymmetric keys yet."
- "There is a hidden import cycle if you import `User` from `models.user` instead of `models`. Always use `from models import User`."
BAD:
- "Be careful." (not specific)
- "There might be bugs." (not actionable)
### `files_in_progress` (array of objects)
Files currently mid-edit or partially complete. Include the state so the next session knows whether to read, edit, or review.
| state | meaning |
|-------|---------|
| `editing` | Actively being modified, may not compile |
| `needs_review` | Changes complete but unverified |
| `partially_done` | Some functions done, others stubbed |
| `ready` | Complete and tested |
### `decisions_made` (array of objects)
Architectural decisions taken during the current session, with rationale and timestamp. These should also be promoted to a project-wide decision log when significant.
```json
{
"decision": "Use HS256 instead of RS256 for JWT signing",
"rationale": "Secret rotation tooling does not support asymmetric keys; we accept the tradeoff because token lifetime is 15 minutes",
"timestamp": "2026-04-05T14:32:00+00:00"
}
```
## Handoff Lifecycle
### When to write the handoff
- At every natural milestone (feature complete, tests passing, EOD)
- BEFORE the session is likely to expire
- Whenever a blocker is hit
- Whenever a non-obvious decision is made
### How to write it (non-blocking)
Spawn a background subagent so the main agent doesn't pause:
> "Read `docs/TC/records/<TC-ID>/tc_record.json`. Update the handoff section with: progress_summary='...'; add next_step '...'; add blocker '...'. Use `tc_update.py` so revision history is appended. Then update `last_active` and write atomically."
### How the next session reads it
1. Read `docs/TC/tc_registry.json` and find TCs with status `in_progress` or `blocked`.
2. Read `tc_record.json` for each.
3. Display the handoff block to the user.
4. Ask: "Resume <TC-ID>? (y/n)"
5. If yes:
- Archive the previous session's `current_session` into `session_history` with an `ended` timestamp and a summary.
- Create a new `current_session` for the new bot.
- Append a revision: "Session resumed by <platform/model>".
- Walk through `next_steps` in order.
## Quality Bar
A handoff is "good" if a fresh AI session, with no other context, can pick up the work and make progress within 5 minutes of reading the record. If the next session has to ask "what was I doing?" or "what does this code do?", the previous handoff failed.
## Anti-patterns
| Anti-pattern | Why it's bad |
|--------------|--------------|
| Empty handoff at session end | Defeats the entire purpose |
| `next_steps: ["continue"]` | Not actionable |
| Handoff written but never updated as work progresses | Goes stale within an hour |
| Decisions buried in `notes` instead of `decisions_made` | Loses the rationale |
| Files mid-edit but not listed in `files_in_progress` | Next session reads stale code |
| Blockers in `notes` instead of `blockers` array | TC status cannot be set to `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 |