[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-a588bc7e-c87b-4289-a8ce-22e88d9a6980":3,"$fft-vr1Hvku13nuhrUw593Y7B2hhZKr0LrtC77jM-Y2A":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"a588bc7e-c87b-4289-a8ce-22e88d9a6980","tc-tracker","使用时，当用户要求跟踪技术变更、创建变更记录、管理TC生命周期或在不同AI会话之间移交工作时。涵盖结构化代码变更文档的初始化\u002F创建\u002F更新\u002F状态\u002F恢复\u002F关闭\u002F导出工作流程。","cat_life_career","mod_other","alirezarezvani,other","---\nname: \"tc-tracker\"\ndescription: \"Use when the user asks to track technical changes, create change records, manage TC lifecycles, or hand off work between AI sessions. Covers init\u002Fcreate\u002Fupdate\u002Fstatus\u002Fresume\u002Fclose\u002Fexport workflows for structured code change documentation.\"\n---\n\n# TC Tracker\n\nTrack every code change with structured JSON records, an enforced state machine, and a session handoff format that lets a new AI session resume work cleanly when a previous one expires.\n\n## Overview\n\nA 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. Records live as JSON in `docs\u002FTC\u002F` inside the target project, validated against a strict schema and a state machine.\n\n**Use this skill when the user:**\n- Asks to \"track this change\" or wants an audit trail for code modifications\n- Wants to hand off in-progress work to a future AI session\n- Needs structured release notes that go beyond commit messages\n- Onboards an existing project and wants retroactive change documentation\n- Asks for `\u002Ftc init`, `\u002Ftc create`, `\u002Ftc update`, `\u002Ftc status`, `\u002Ftc resume`, or `\u002Ftc close`\n\n**Do NOT use this skill when:**\n- The user only wants a changelog from git history (use `engineering\u002Fchangelog-generator`)\n- The user only wants to track tech debt items (use `engineering\u002Ftech-debt-tracker`)\n- The change is trivial (typo, formatting) and won't affect behavior\n\n## Storage Layout\n\nEach project stores TCs at `{project_root}\u002Fdocs\u002FTC\u002F`:\n\n```\ndocs\u002FTC\u002F\n├── tc_config.json          # Project settings\n├── tc_registry.json        # Master index + statistics\n├── records\u002F\n│   └── TC-001-04-05-26-user-auth\u002F\n│       └── tc_record.json  # Source of truth\n└── evidence\u002F\n    └── TC-001\u002F             # Log snippets, command output, screenshots\n```\n\n## TC ID Convention\n\n- **Parent TC:** `TC-NNN-MM-DD-YY-functionality-slug` (e.g., `TC-001-04-05-26-user-authentication`)\n- **Sub-TC:** `TC-NNN.A` or `TC-NNN.A.1` (letter = revision, digit = sub-revision)\n- `NNN` is sequential, `MM-DD-YY` is the creation date, slug is kebab-case.\n\n## State Machine\n\n```\nplanned -> in_progress -> implemented -> tested -> deployed\n   |            |              |           |          |\n   +-> blocked -+              +- in_progress \u003C-------+\n        |                          (rework \u002F hotfix)\n        +-> planned\n```\n\n> See [references\u002Flifecycle.md](references\u002Flifecycle.md) for the full transition table and recovery flows.\n\n## Workflow Commands\n\nThe skill ships five Python scripts that perform deterministic, stdlib-only operations on TC records. Each one supports `--help` and `--json`.\n\n### 1. Initialize tracking in a project\n\n```bash\npython3 scripts\u002Ftc_init.py --project \"My Project\" --root .\n```\n\nCreates `docs\u002FTC\u002F`, `docs\u002FTC\u002Frecords\u002F`, `docs\u002FTC\u002Fevidence\u002F`, `tc_config.json`, and `tc_registry.json`. Idempotent — re-running reports \"already initialized\" with current stats.\n\n### 2. Create a new TC record\n\n```bash\npython3 scripts\u002Ftc_create.py \\\n  --root . \\\n  --name \"user-authentication\" \\\n  --title \"Add JWT-based user authentication\" \\\n  --scope feature \\\n  --priority high \\\n  --summary \"Adds JWT login + middleware\" \\\n  --motivation \"Required for protected endpoints\"\n```\n\nGenerates the next sequential TC ID, creates the record directory, writes a fully populated `tc_record.json` (status `planned`, R1 creation revision), and updates the registry.\n\n### 3. Update a TC record\n\n```bash\n# Status transition (validated against the state machine)\npython3 scripts\u002Ftc_update.py --root . --tc-id TC-001-04-05-26-user-auth \\\n  --set-status in_progress --reason \"Starting implementation\"\n\n# Add a file\npython3 scripts\u002Ftc_update.py --root . --tc-id TC-001-04-05-26-user-auth \\\n  --add-file src\u002Fauth.py:created\n\n# Append handoff data\npython3 scripts\u002Ftc_update.py --root . --tc-id TC-001-04-05-26-user-auth \\\n  --handoff-progress \"JWT middleware wired up\" \\\n  --handoff-next \"Write integration tests\" \\\n  --handoff-next \"Update README\"\n```\n\nEvery change appends a sequential `R\u003Cn>` revision entry, refreshes `updated`, and re-validates against the schema before writing atomically (`.tmp` then rename).\n\n### 4. View status\n\n```bash\n# Single TC\npython3 scripts\u002Ftc_status.py --root . --tc-id TC-001-04-05-26-user-auth\n\n# All TCs (registry summary)\npython3 scripts\u002Ftc_status.py --root . --all --json\n```\n\n### 5. Validate a record or registry\n\n```bash\npython3 scripts\u002Ftc_validator.py --record docs\u002FTC\u002Frecords\u002FTC-001-...\u002Ftc_record.json\npython3 scripts\u002Ftc_validator.py --registry docs\u002FTC\u002Ftc_registry.json\n```\n\nValidator enforces the schema, checks state-machine legality, verifies sequential `R\u003Cn>` and `T\u003Cn>` IDs, and asserts approval consistency (`approved=true` requires `approved_by` and `approved_date`).\n\n> See [references\u002Ftc-schema.md](references\u002Ftc-schema.md) for the full schema.\n\n## Slash-Command Dispatcher\n\nThe repo ships a `\u002Ftc` slash command at `commands\u002Ftc.md` that dispatches to these scripts based on subcommand:\n\n| Command | Action |\n|---------|--------|\n| `\u002Ftc init` | Run `tc_init.py` for the current project |\n| `\u002Ftc create \u003Cname>` | Prompt for fields, run `tc_create.py` |\n| `\u002Ftc update \u003Ctc-id>` | Apply user-described changes via `tc_update.py` |\n| `\u002Ftc status [tc-id]` | Run `tc_status.py` |\n| `\u002Ftc resume \u003Ctc-id>` | Display handoff, archive prior session, start a new one |\n| `\u002Ftc close \u003Ctc-id>` | Transition to `deployed`, set approval |\n| `\u002Ftc export` | Re-render all derived artifacts |\n| `\u002Ftc dashboard` | Re-render the registry summary |\n\nThe slash command is the user interface; the Python scripts are the engine.\n\n## Session Handoff Format\n\nThe handoff block lives at `session_context.handoff` inside each TC and is the single most important field for AI continuity. It contains:\n\n- `progress_summary` — what has been done\n- `next_steps` — ordered list of remaining actions\n- `blockers` — anything preventing progress\n- `key_context` — critical decisions, gotchas, patterns the next bot must know\n- `files_in_progress` — files being edited and their state (`editing`, `needs_review`, `partially_done`, `ready`)\n- `decisions_made` — architectural decisions with rationale and timestamp\n\n> See [references\u002Fhandoff-format.md](references\u002Fhandoff-format.md) for the full structure and fill-out rules.\n\n## Validation Rules (Always Enforced)\n\n1. **State machine** — only valid transitions are allowed.\n2. **Sequential IDs** — `revision_history` uses `R1, R2, R3...`; `test_cases` uses `T1, T2, T3...`.\n3. **Append-only history** — revision entries are never modified or deleted.\n4. **Approval consistency** — `approved=true` requires `approved_by` and `approved_date`.\n5. **TC ID format** — must match `TC-NNN-MM-DD-YY-slug`.\n6. **Sub-TC ID format** — must match `TC-NNN.A` or `TC-NNN.A.N`.\n7. **Atomic writes** — JSON is written to `.tmp` then renamed.\n8. **Registry stats** — recomputed on every registry write.\n\n## Non-Blocking Bookkeeping Pattern\n\nTC tracking must NOT interrupt the main workflow.\n\n- **Never stop to update TC records inline.** Keep coding.\n- At natural milestones, spawn a background subagent to update the record.\n- Surface questions only when genuinely needed (\"This work doesn't match any active TC — create one?\"), and ask once per session, not per file.\n- At session end, write a final handoff block before closing.\n\n## Retroactive Bulk Creation\n\nFor onboarding an existing project with undocumented history, build a `retro_changelog.json` (one entry per logical change) and feed it to `tc_create.py` in a loop, or extend the script for batch mode. Group commits by feature, not by file.\n\n## Anti-Patterns\n\n| Anti-pattern | Why it's bad | Do this instead |\n|--------------|--------------|-----------------|\n| Editing `revision_history` to \"fix\" a typo | History is append-only — tampering destroys the audit trail | Add a new revision that corrects the field |\n| Skipping the state machine (\"just set status to deployed\") | Bypasses validation and hides skipped phases | Walk through `in_progress -> implemented -> tested -> deployed` |\n| Creating one TC per file changed | Fragments related work and explodes the registry | One TC per logical unit (feature, fix, refactor) |\n| Updating TC inline between every code edit | Slows the main agent, wastes context | Spawn a background subagent at milestones |\n| Marking `approved=true` without `approved_by` | Validator will reject; misleading audit trail | Always set `approved_by` and `approved_date` together |\n| Overwriting `tc_record.json` directly with a text editor | Risks corruption mid-write and skips validation | Use `tc_update.py` (atomic write + schema check) |\n| Putting secrets in `notes` or evidence | Records are committed to the repo | Reference an env var or external secret store |\n| Reusing TC IDs after deletion | Breaks the sequential guarantee and confuses history | Increment forward only — never recycle |\n| Letting `next_steps` go stale | Defeats the purpose of handoff | Update on every milestone, even if it's \"nothing changed\" |\n\n## Cross-References\n\n- `engineering\u002Fchangelog-generator` — Generates Keep-a-Changelog release notes from Conventional Commits. Pair it with TC tracker: TC for the granular per-change audit trail, changelog for user-facing release notes.\n- `engineering\u002Ftech-debt-tracker` — For tracking long-lived debt items rather than discrete code changes.\n- `engineering\u002Ffocused-fix` — When a bug fix needs systematic feature-wide repair, run `\u002Ffocused-fix` first then capture the result as a TC.\n- `project-management\u002Fdecision-log` — Architectural decisions made inside a TC's `decisions_made` block can also be promoted to a project-wide decision log.\n- `engineering-team\u002Fcode-reviewer` — Pre-merge review fits naturally into the `tested -> deployed` transition; capture the reviewer in `approval.approved_by`.\n\n## References in This Skill\n\n- [references\u002Ftc-schema.md](references\u002Ftc-schema.md) — Full JSON schema for TC records and the registry.\n- [references\u002Flifecycle.md](references\u002Flifecycle.md) — State machine, valid transitions, and recovery flows.\n- [references\u002Fhandoff-format.md](references\u002Fhandoff-format.md) — Session handoff structure and best practices.\n","","imported","https:\u002F\u002Fgithub.com\u002Falirezarezvani\u002Fclaude-skills","user_system_seed","SkillOPIC",true,130,273,"2026-05-16 13:55:41",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"其他","other","mdi-page-next-outline","其他类型Skill",5,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"职场发展","career","mdi-briefcase-outline","面试准备、简历优化、职业规划",4,575,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"96be6bec-7c4d-40ab-ac9f-78b4916bb5e8","1.0.0","tc-tracker.zip",27755,"uploads\u002Fskills\u002Fa588bc7e-c87b-4289-a8ce-22e88d9a6980\u002Ftc-tracker.zip","c09fb9267ae7871049ce6d4e55eb54cc9500c9364ed1d09db06444ccf8590c90","[{\"path\":\"README.md\",\"isDirectory\":false,\"size\":2278},{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":10325},{\"path\":\"references\u002Fhandoff-format.md\",\"isDirectory\":false,\"size\":5291},{\"path\":\"references\u002Flifecycle.md\",\"isDirectory\":false,\"size\":4037},{\"path\":\"references\u002Ftc-schema.md\",\"isDirectory\":false,\"size\":5386},{\"path\":\"scripts\u002Ftc_create.py\",\"isDirectory\":false,\"size\":9936},{\"path\":\"scripts\u002Ftc_init.py\",\"isDirectory\":false,\"size\":6861},{\"path\":\"scripts\u002Ftc_status.py\",\"isDirectory\":false,\"size\":7335},{\"path\":\"scripts\u002Ftc_update.py\",\"isDirectory\":false,\"size\":14181},{\"path\":\"scripts\u002Ftc_validator.py\",\"isDirectory\":false,\"size\":14226}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]