| name | techdebt |
| description | Produces a normalized tech-debt entry in chat — date-stamped, with auto-filled git context (branch + short commit). The entry is text-only output; the main agent decides whether to append it to `docs/techdebt.md` (the convention), file a GitHub issue, or surface it elsewhere per the downstream CLAUDE.md's policy. Use when a reviewer surfaces a `[DECISION]` critical or pre-existing tech-debt observation worth recording, or when the main agent notices a non-actionable smell during work. |
| tools | Bash |
Skill — techdebt
Produces a normalized tech-debt entry. Output-only — the skill never writes to disk.
The kit owns the format; the main agent (governed by the downstream CLAUDE.md) owns the destination. Convention: append to docs/techdebt.md, sibling to docs/todo.md. Format consistency across projects is the value the skill provides; whats-next reads from the conventional location.
Required tools
Bash — for current date and git context (branch + short commit hash) auto-fill.
When to use
- A reviewer emits a
[DECISION] critical the main agent decides not to fix in this branch
- A reviewer's
### ℹ️ Pre-existing tech debt section flags something worth tracking
- The main agent notices a non-actionable smell during work (cross-cutting issue, brittle pattern) and wants a normalized record
Not for action items the user is committing to today — those belong in docs/todo.md. Tech-debt entries are observations, not commitments. They describe what's odd, not what to do.
Execution Steps
Step 1 — Collect inputs
Required:
where — file path with optional line/range (src/foo.ts:42, src-tauri/capabilities/), or a non-file scope (across the IPC layer)obs — one-line observation: the smell, the surprise, the inconsistency. Not the fixfound-by — source: a reviewer name (reviewer-arch, reviewer-security), kit-discover, or manual
Optional:
title — short title (≤60 chars). Defaults to obs truncated at the nearest word boundaryseverity — one of 🔴 / 🟡 / 🔵, or a label (low / medium / high). Omit if unknown — do not manufacture
If a required input is missing or empty → ask the user to supply it before proceeding. Do not invent values.
Step 2 — Auto-fill date and git context
Run each as a separate Bash call:
date +%Y-%m-%d
git rev-parse --abbrev-ref HEAD 2>/dev/null
git rev-parse --short HEAD 2>/dev/null
If not a git repo → the context line reads (no git context). If detached HEAD → use the commit hash only.
Step 3 — Validate the observation isn't a fix
If obs reads like an instruction (refactor X, replace Y with Z, extract, move, delete, add, fix, etc.) → ask the user to rephrase as a description of what's wrong, not what to do. Tech-debt entries lose their value when they prescribe a fix that may turn out to be wrong on closer look — and overlap with docs/todo.md.
Step 4 — Emit the normalized block
Output as plain markdown text in the chat (the main agent should be able to copy it verbatim into a file or paste into an issue tracker). Schema:
## {YYYY-MM-DD} — {title}
- Found by: {found-by}
- Where: {where}
- Context: branch `{branch}` @ `{short-commit}`
- Severity: {severity}
- Observation: {obs}
Omit the Severity: line entirely when no severity was provided. Replace the Context value with (no git context) when not in a git repo.
After the block, append one short follow-up line:
Convention: append to docs/techdebt.md. The main agent decides the final destination.
Do not write to any file. Do not ask the user where to put it — that's the main agent's call, governed by the downstream CLAUDE.md.
Critical Rules
- Output-only — never write, edit, or append to any file. The skill's job is normalization, not persistence. Persistence is the main agent's call.
- Observations, not fixes — the
Observation field describes what's wrong; it must not say what to do. If the user's obs reads like an instruction, ask them to rephrase.
- No fabricated context — if git or any required input is unavailable, say so explicitly (
(no git context), prompt for missing input). Never invent values.
- No severity by default — only include the
Severity: line when the user provides one. Don't invent severity to make the entry look richer.
- One entry per invocation — the skill produces one normalized block. Batches go through repeated invocations or a main-agent loop; this skill stays single-purpose.
Notes
This skill complements the [DECISION] reviewer tag (see kit-readme.md § "Handling [DECISION] Criticals"). Reviewers flag; the main agent decides; this skill normalizes the persisted record.
whats-next reads docs/techdebt.md (when present) and surfaces entries as work candidates alongside TODOs, plans, and specs — with the source labelled docs/techdebt.md (DATE) so the user can tell observations from explicit todos. The "observation, not fix" framing applies to how entries are written (capture the smell, not the prescription); once captured, an entry is fair game for triage and scoring like any other backlog item.
