add
Register a deferred decision in the debt registry. Trigger by judgment, not a marker scan, whenever a future reader would ask "why this way?": an unmade decision, stub, loosened type, bypassed check, swallowed error, a default picked "for now", or a TODO/FIXME/HACK/XXX marker. Trigger immediately whenever you defer work, or when the user invokes $add. Over-register freely; the developer drops with "drop A", "drop A,C", or "drop all".
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- add
- description
- Register a deferred decision in the debt registry. Trigger by judgment, not a marker scan, whenever a future reader would ask "why this way?": an unmade decision, stub, loosened type, bypassed check, swallowed error, a default picked "for now", or a TODO/FIXME/HACK/XXX marker. Trigger immediately whenever you defer work, or when the user invokes $add. Over-register freely; the developer drops with "drop A", "drop A,C", or "drop all".
02 资源文件 1
- 脚本scripts/register.py6.2 KB
03 SKILL.md 正文
add — register a tech-debt entry
Call the bundled register.py via Bash — it lives in this skill's scripts/ directory, so reference it with the relative path below (Codex resolves it against the skill root). The helper writes the entry under the repo's detected registry dir (default docs/debt/), assigns a short batch letter (A, B, C…), and prints exactly one line: +1 entry: <slug> (<letter>). That stdout IS the user-facing announcement — add no commentary before or after.
The call
python3 scripts/register.py \
--slug <slug> \
--principal <effort, e.g. 2d, 1w, unknown> \
--interest <ongoing cost, e.g. "+30min/incident", unknown> \
--hotspot <path or module, e.g. pricing/engine.ts, unknown> \
--business-capability <e.g. checkout, billing, unknown> \
--payoff-trigger <concrete trigger, or "unknown"> \
--quadrant <reckless-inadvertent|reckless-deliberate|prudent-inadvertent|prudent-deliberate> \
--category <migration|documentation|testing|code_quality|dead_code|code_rot|expertise|release|infrastructure|planning> \
--ai-authored <true|false> <<'EOF'
<body: 2-5 sentences — what the debt is, why it exists, observed symptoms>
EOF
The helper:
- Generates the timestamp
iditself (nodatecall needed). - Resolves filename collisions when two registrations land in the same second.
- Tracks the letter mapping in
~/.cache/debt-ops/cache/<repo-hash>/current-turn.txt(override the base withDEBT_OPS_CACHE) so the user can drop by letter.
Slug
1–4 word kebab-case label of what the debt is. Examples: cancelled-promotion-callback, legacy-auth-shim, unfinished-rate-limiter. Keep it short — the body carries the context.
Schema notes
- Quadrant (Fowler):
reckless-inadvertent(didn't know better),reckless-deliberate(knew, did it anyway),prudent-inadvertent(learned afterward),prudent-deliberate(deliberate, with a payoff plan). - Category (Google / Jaspan-Green): pick the closest match.
- payoff_trigger: unknown is first-class. Don't manufacture a trigger to fill the field —
unknownages into stale review and that's the point. - ai_authored: true is the leading behavioral signal — be honest.
Drops
drop A,drop A,C,drop all— the user types this; a UserPromptSubmit hook deletes the matching entries and surfaces a one-line confirmation. You don't act on those.drop itordrop <slug>— you delete it yourself:rm <registry-dir>/<id>-<slug>.md(the registry dir named in Discipline 3; defaultdocs/debt/). Treat dropping as cheap — over-registering is the intended posture.
Don't
- Don't ask the developer for confirmation before writing. Discipline 1 says "no permission prompt; just do it."
- Don't write the file directly with an editor tool — letter assignment depends on going through
register.py. - Don't echo or paraphrase the helper's output. The Bash tool result is already visible to the user.
- Don't fill
payoff_triggerwith a guess to seem certain.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.