JantonioFC/skillsbank

/tc — 技术变更跟踪器

发送 TC（技术变更）命令。参数：$ARGUMENTS。

如果 $ARGUMENTS 为空，则打印以下菜单并停止：

/tc init                       在此项目中初始化 TC 跟踪
/tc create <name>              创建新的 TC 记录
/tc update <tc-id> [...]       更新字段、状态、文件、交接
/tc status [tc-id]             显示单个 TC 或注册表摘要
/tc resume <tc-id>             从之前的会话恢复 TC
/tc close <tc-id>              将 TC 转换为已部署状态
/tc export                     重新渲染衍生工件
/tc dashboard                  重新渲染注册表摘要

否则，将 $ARGUMENTS 解析为 <subcommand> <rest> 并分派到下方匹配的协议。所有脚本位于 engineering/tc-tracker/scripts/。

子命令

init

1. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_init.py --root . --json
   

2. 如果状态为 already_initialized，报告当前统计信息并停止。
3. 否则报告已创建的内容并建议下一步执行 /tc create <name>。

create <name>

1. 将 <name> 解析为 kebab-case 形式的 slug。如果缺失，请求用户提供一个。
2. 逐一询问用户以下信息：
   • 标题（5-120 个字符）
   • 范围：feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement
   • 优先级：critical | high | medium | low（默认为 medium）
   • 摘要（至少 10 个字符）
   • 动机
3. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_create.py --root . \
     --name "<slug>" --title "<title>" --scope <scope> --priority <priority> \
     --summary "<summary>" --motivation "<motivation>" --json
   

4. 报告新的 TC ID 和记录的路径。

update <tc-id> [intent]

1. 如果 <tc-id> 缺失，从 tc_status.py --all 列出活动的 TC（状态为 in_progress 或 blocked）并询问选择哪一个。
2. 从自然语言中确定用户的意图：
   • 状态变更 → --set-status <state> 加上 --reason "<why>"
   • 添加文件 → 一个或多个 --add-file path[:action]
   • 添加测试 → --add-test "<title>" --test-procedure "<step>" --test-expected "<result>"
   • 更新交接 → 任意组合 --handoff-progress、--handoff-next、--handoff-blocker、--handoff-context
   • 添加备注 → --note "<text>"
   • 添加标签 → --tag <tag>
3. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json
   

4. 如果退出码非零，直接显示错误。状态机和验证器会拒绝无效操作——不要盲目重试。

status [tc-id]

• 如果提供了 <tc-id>：

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>
  

• 否则：

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all
  

resume <tc-id>

1. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json
   

2. 突出显示交接块：progress_summary、next_steps（编号）、blockers、key_context。
3. 询问：“恢复 并从下一个步骤 1 开始？(y/n)”
4. 如果回答是，运行更新以记录恢复操作：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --note "Session resumed" --reason "session handoff"
   

5. 开始执行 next_steps 中的第一项。不要重新推导上下文——信任交接信息。

close <tc-id>

1. 通过 tc_status.py --tc-id <tc-id> --json 读取记录。
2. 验证当前状态是否为 tested。如果不是，拒绝并告知用户仍然需要哪些转换。
3. 检查 test_cases：如果有任何状态为 pending、fail 或 blocked，则发出警告。
4. 询问用户：
   • “谁在批准？（您的姓名，或‘self’）”
   • “批准备注（可选）：”
   • “测试覆盖率状态：none / partial / full”
5. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --set-status deployed --reason "Approved by <approver>" --note "Approval: <approver> — <notes>"
   

   然后，如果您的脚本版本支持，通过后续更新直接编辑 approval 块；否则指示用户在备注中记录批准信息。
6. 报告：“TC-NNN 已关闭并部署。”

export

此技能中没有自动的 HTML 导出功能。而是重新验证所有内容：

1. 读取注册表。
2. 对每条记录运行：

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --record <path> --json
   

3. 运行：

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json
   

4. 报告：已验证的记录总数、任何错误以及无效内容的路径。

dashboard

运行所有记录摘要：

python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all

铁律

1. 切勿手动编辑 tc_record.json。 始终使用 tc_update.py，以便追加修订历史并运行验证。
2. 切勿跳过状态机。 即使感觉冗余，也要依次推进状态。
3. 切勿删除 TC。 历史只能追加——添加最终修订并标记为 [CANCELLED]。
4. 后台记账。 在任务进行中时，生成一个后台子代理来更新 TC。不要暂停编码去处理文书工作。
5. 在报告成功前进行验证。 如果脚本退出码非零，显示错误并停止。

相关技能

• engineering/tc-tracker — 完整的 SKILL.md，包含模式参考、生命周期示意图和交接格式。
• engineering/changelog-generator — 与 TC 跟踪器配对：TC 用于每次变更的审计追踪，changelog 用于面向用户的发布说明。
• engineering/tech-debt-tracker — 用于跟踪长期存在的技术债务，而非离散的代码变更。