Priority determines resolution order, not permission to accumulate indefinitely — every known issue (bug, inconsistency, TODO, workaround, deferred P3) must terminate in resolved, explicitly rejected with a reason, or documented as an open unresolved constraint, never silently vanish by being written down. Use whenever triaging bugs/findings/technical debt, prioritizing a backlog, closing a task under time pressure, or reviewing whether a TODO/workaround/deferred item has actually been addressed. Trigger on "P0/P1/P2/P3", "backlog", "leave this for later", "known issue", "TODO", "technical debt", "we'll clean this up eventually", "out of scope for now". A module whose patch history has become hard to read triggers software-archaeology's replacement procedure, not a repeat of it here — see below.
Priority determines resolution order, not permission to accumulate
indefinitely.
P0/P1/P2/P3 (or any priority scheme) says when something gets worked, in
what order. It does not say that the lowest tier may sit forever as an
unaddressed, semantically-closed item just because someone wrote it down.
This skill governs the second half of that sentence, which most triage
processes leave unstated.
Composes with the library:
software-archaeology — already contains the full mechanism for a
module whose accumulated patches have made its intended semantics hard to
read: prefer parallel-run over cutover, expand-migrate-contract over
in-place mutation, characterization tests before changing behavior, and
git log/blame to extract original intent. This skill does not restate
that mechanism — it only names the trigger: when a patched module's
history obscures its intended behavior for a reader, that's a
software-archaeology job, not something this skill will improvise its own
version of.
decision-record-discipline — "explicitly rejected with a reason" (one
of this skill's three terminal states) is that skill's Alternatives-
rejected field, applied to a piece of debt instead of a design choice.
Use that skill's structure to record the rejection; don't invent a
second format.
beyond-the-fix — that skill audits whether a shipped fix is actually
complete (root cause, variant sweep, blast radius). This skill governs
what happens to an item before it's fixed — the queue discipline, not
the fix-quality audit. A fix that closes an item under this skill's
discipline still owes beyond-the-fix's scrutiny before the item is
actually marked resolved.
known-defect-disposition — this skill's state 3 ("documented as an
open, unresolved constraint") is exactly the deferral that skill gates:
before any P2–P4 finding is allowed into state 3, it requires an
escalation analysis (can interaction, composition, or adversarial control
raise its severity) and a structured record with a revisit trigger, not a
bare note that it exists. Use this skill's three-state framing to decide
where a defect lands; use that skill's gate and record format to decide
how it gets there when the defect is a security- or correctness-bearing
finding under priority triage.
git-discipline — "history belongs in version control ... not in the
active control flow" (below) leans on that skill's forward-only,
recoverable history as the place old context actually lives.
Every known issue ends in one of three states
MUST resolve every known issue — a bug, an inconsistency, a TODO, a
workaround, a deferred lower-priority item — to exactly one of three
terminal states, and MUST NOT let it exist indefinitely in none of them:
Resolved. The issue is fixed, verified, and (per beyond-the-fix)
checked for whether the fix is actually complete, not just present.
Explicitly rejected, with a reason. A deliberate decision that this
will not be addressed — recorded the way decision-record-discipline
records any rejected alternative: what was considered, why it lost, and
what would reopen the question.
Documented as an open, unresolved constraint. Time ran out, priority
ranked it below what got done, or it depends on something not yet
available — and it is recorded as still open, with enough context
(what it is, why it matters, what would be needed to close it) that
whoever picks it up next doesn't have to reconstruct that from scratch.
Documented is not a fourth, easier state — it is state 3, and state 3 is
still open. Writing an item down does not resolve it; it only makes the
open item legible instead of silent. A TODO comment, a backlog ticket, or a
"known limitation" note that nobody tracks as still-outstanding is
functionally identical to the issue having vanished — the code and the
record both look finished when neither is.
What this is not
This is not a rule against triage, against deprioritizing genuinely
lower-value work, or against shipping with known limitations. Priority
tiers exist and are respected — P3 legitimately means "not now." What
MUST NOT happen is P3 (or "backlog," or "someday") functioning as a
synonym for this stops being anyone's problem. The distinction is whether
the item remains an open, trackable item in state 3, or silently exits
tracking altogether while still being unresolved.
The patched-module trigger
MUST treat a module whose accumulated patches (compatibility shims,
workarounds, fixes-for-workarounds, special cases) have made its actually-
intended behavior hard for a reader to determine as the trigger for
software-archaeology's replacement procedure — not a threshold to hit a
specific patch count against. MUST NOT assign an arbitrary numeric
threshold ("5 patches," "3 workarounds") for this judgment; it is a
qualitative call about whether the current reader can still tell what the
module is supposed to do, and that call is made by actually trying to state
the module's intended behavior in one paragraph — if that paragraph
requires reading the patch history to write, the trigger has been met.
History belongs in version control and decision records, not in the active control flow
MUST NOT keep dead branches, obsolete compatibility hacks, or comments
that contradict the code's current behavior in the active codebase on the
theory that they were once necessary and might be needed for context.
git-discipline's forward-only, recoverable history is where that
genealogy actually lives and can be recovered if truly needed — production
code should express the design that is currently in effect, not a layered
record of everything it used to be. When software-archaeology's
replacement procedure completes for a patched module, the old
implementation's story belongs in the commit history and, if the decision
to replace it was non-trivial, in a decision-record-discipline entry —
not left inline as a comment block explaining what used to be true.
Failure modes / anti-patterns
P3-as-graveyard: a lower-priority item that stops being tracked
entirely instead of remaining an open item in state 3.
"Documented" mistaken for "closed": a known-limitations note or a TODO
comment treated as if writing it down discharged the obligation to
eventually resolve or explicitly reject it.
Silent scope-narrowing: an item quietly dropped from a plan with no
rejection reason recorded, indistinguishable later from an item nobody
ever noticed.
Threshold-hunting for the patched-module trigger: waiting for an
arbitrary patch count instead of checking whether the module's intended
behavior can still be stated without consulting its patch history.
Reimplementing software-archaeology's replacement mechanism from
scratch inside a debt-triage process instead of composing to it.
Archaeological code: dead branches, retired compatibility shims, or
comments describing old behavior left in the active control flow instead
of in git history or a decision record.
Marking an item resolved without beyond-the-fix scrutiny — closing
state 1 on the presence of a fix rather than its completeness.
Verifiable checks
Every known issue currently tracked resolves to exactly one of:
resolved (with completeness checked), explicitly rejected (with a
recorded reason), or documented as an open unresolved constraint —
none exist outside these three states.
No item marked "documented" or "known limitation" is treated as
closed; each remains visibly trackable as open.
Every explicit rejection has a recorded reason and, where relevant, a
condition that would reopen it — not a bare "won't fix."
A patched module's replacement decision was triggered by an actual
attempt to state its intended behavior in one paragraph (and failing
to, without the patch history), not by an arbitrary patch count.
A patched-module replacement follows software-archaeology's
procedure (parallel-run/expand-migrate-contract, characterization
tests, intent extraction from history) rather than an improvised
variant.
No dead branch, obsolete compatibility hack, or behavior-contradicting
comment remains in the active codebase after a replacement completes
— that history lives in git and, where the decision was non-trivial,
in a decision record.
An item marked resolved has been checked against beyond-the-fix,
not just marked done because a fix exists.
1---2name: debt-closure-discipline3description: Priority determines resolution order, not permission to accumulate indefinitely — every known issue (bug, inconsistency, TODO, workaround, deferred P3) must terminate in resolved, explicitly rejected with a reason, or documented as an open unresolved constraint, never silently vanish by being written down. Use whenever triaging bugs/findings/technical debt, prioritizing a backlog, closing a task under time pressure, or reviewing whether a TODO/workaround/deferred item has actually been addressed. Trigger on "P0/P1/P2/P3", "backlog", "leave this for later", "known issue", "TODO", "technical debt", "we'll clean this up eventually", "out of scope for now". A module whose patch history has become hard to read triggers software-archaeology's replacement procedure, not a repeat of it here — see below.4metadata:5 source: https://skillmd.com/skills/annatchijova/debt-closure-discipline6---78# Debt Closure Discipline910> **Priority determines resolution order, not permission to accumulate11> indefinitely.**1213P0/P1/P2/P3 (or any priority scheme) says *when* something gets worked, in14what order. It does not say that the lowest tier may sit forever as an15unaddressed, semantically-closed item just because someone wrote it down.16This skill governs the second half of that sentence, which most triage17processes leave unstated.1819Composes with the library:2021- **software-archaeology** — already contains the full mechanism for a22 module whose accumulated patches have made its intended semantics hard to23 read: prefer parallel-run over cutover, expand-migrate-contract over24 in-place mutation, characterization tests before changing behavior, and25 git log/blame to extract original intent. This skill does not restate26 that mechanism — it only names the trigger: when a patched module's27 history obscures its intended behavior for a reader, that's a28 software-archaeology job, not something this skill will improvise its own29 version of.30- **decision-record-discipline** — "explicitly rejected with a reason" (one31 of this skill's three terminal states) is that skill's Alternatives-32 rejected field, applied to a piece of debt instead of a design choice.33 Use that skill's structure to record the rejection; don't invent a34 second format.35- **beyond-the-fix** — that skill audits whether a *shipped* fix is actually36 complete (root cause, variant sweep, blast radius). This skill governs37 what happens to an item *before* it's fixed — the queue discipline, not38 the fix-quality audit. A fix that closes an item under this skill's39 discipline still owes `beyond-the-fix`'s scrutiny before the item is40 actually marked resolved.41- **known-defect-disposition** — this skill's state 3 ("documented as an42 open, unresolved constraint") is exactly the deferral that skill gates:43 before any P2–P4 finding is allowed into state 3, it requires an44 escalation analysis (can interaction, composition, or adversarial control45 raise its severity) and a structured record with a revisit trigger, not a46 bare note that it exists. Use this skill's three-state framing to decide47 *where* a defect lands; use that skill's gate and record format to decide48 *how* it gets there when the defect is a security- or correctness-bearing49 finding under priority triage.50- **git-discipline** — "history belongs in version control ... not in the51 active control flow" (below) leans on that skill's forward-only,52 recoverable history as the place old context actually lives.5354---5556## Every known issue ends in one of three states5758**MUST** resolve every known issue — a bug, an inconsistency, a TODO, a59workaround, a deferred lower-priority item — to exactly one of three60terminal states, and **MUST NOT** let it exist indefinitely in none of them:61621. **Resolved.** The issue is fixed, verified, and (per `beyond-the-fix`)63 checked for whether the fix is actually complete, not just present.642. **Explicitly rejected, with a reason.** A deliberate decision that this65 will not be addressed — recorded the way `decision-record-discipline`66 records any rejected alternative: what was considered, why it lost, and67 what would reopen the question.683. **Documented as an open, unresolved constraint.** Time ran out, priority69 ranked it below what got done, or it depends on something not yet70 available — and it is recorded as **still open**, with enough context71 (what it is, why it matters, what would be needed to close it) that72 whoever picks it up next doesn't have to reconstruct that from scratch.7374**Documented is not a fourth, easier state — it is state 3, and state 3 is75still open.** Writing an item down does not resolve it; it only makes the76open item legible instead of silent. A TODO comment, a backlog ticket, or a77"known limitation" note that nobody tracks as still-outstanding is78functionally identical to the issue having vanished — the code and the79record both look finished when neither is.8081## What this is not8283This is not a rule against triage, against deprioritizing genuinely84lower-value work, or against shipping with known limitations. Priority85tiers exist and are respected — P3 legitimately means "not now." What86**MUST NOT** happen is P3 (or "backlog," or "someday") functioning as a87synonym for *this stops being anyone's problem*. The distinction is whether88the item remains an open, trackable item in state 3, or silently exits89tracking altogether while still being unresolved.9091## The patched-module trigger9293**MUST** treat a module whose accumulated patches (compatibility shims,94workarounds, fixes-for-workarounds, special cases) have made its actually-95intended behavior hard for a reader to determine as the trigger for96`software-archaeology`'s replacement procedure — not a threshold to hit a97specific patch count against. **MUST NOT** assign an arbitrary numeric98threshold ("5 patches," "3 workarounds") for this judgment; it is a99qualitative call about whether the *current reader* can still tell what the100module is supposed to do, and that call is made by actually trying to state101the module's intended behavior in one paragraph — if that paragraph102requires reading the patch history to write, the trigger has been met.103104## History belongs in version control and decision records, not in the active control flow105106**MUST NOT** keep dead branches, obsolete compatibility hacks, or comments107that contradict the code's current behavior in the active codebase on the108theory that they were once necessary and might be needed for context.109`git-discipline`'s forward-only, recoverable history is where that110genealogy actually lives and can be recovered if truly needed — production111code should express the design that is *currently* in effect, not a layered112record of everything it used to be. When `software-archaeology`'s113replacement procedure completes for a patched module, the old114implementation's story belongs in the commit history and, if the decision115to replace it was non-trivial, in a `decision-record-discipline` entry —116not left inline as a comment block explaining what used to be true.117118## Failure modes / anti-patterns119120- **P3-as-graveyard**: a lower-priority item that stops being tracked121 entirely instead of remaining an open item in state 3.122- **"Documented" mistaken for "closed"**: a known-limitations note or a TODO123 comment treated as if writing it down discharged the obligation to124 eventually resolve or explicitly reject it.125- **Silent scope-narrowing**: an item quietly dropped from a plan with no126 rejection reason recorded, indistinguishable later from an item nobody127 ever noticed.128- **Threshold-hunting for the patched-module trigger**: waiting for an129 arbitrary patch count instead of checking whether the module's intended130 behavior can still be stated without consulting its patch history.131- **Reimplementing software-archaeology's replacement mechanism from132 scratch** inside a debt-triage process instead of composing to it.133- **Archaeological code**: dead branches, retired compatibility shims, or134 comments describing old behavior left in the active control flow instead135 of in git history or a decision record.136- **Marking an item resolved without `beyond-the-fix` scrutiny** — closing137 state 1 on the presence of a fix rather than its completeness.138139## Verifiable checks140141- [ ] Every known issue currently tracked resolves to exactly one of:142 resolved (with completeness checked), explicitly rejected (with a143 recorded reason), or documented as an open unresolved constraint —144 none exist outside these three states.145- [ ] No item marked "documented" or "known limitation" is treated as146 closed; each remains visibly trackable as open.147- [ ] Every explicit rejection has a recorded reason and, where relevant, a148 condition that would reopen it — not a bare "won't fix."149- [ ] A patched module's replacement decision was triggered by an actual150 attempt to state its intended behavior in one paragraph (and failing151 to, without the patch history), not by an arbitrary patch count.152- [ ] A patched-module replacement follows `software-archaeology`'s153 procedure (parallel-run/expand-migrate-contract, characterization154 tests, intent extraction from history) rather than an improvised155 variant.156- [ ] No dead branch, obsolete compatibility hack, or behavior-contradicting157 comment remains in the active codebase after a replacement completes158 — that history lives in git and, where the decision was non-trivial,159 in a decision record.160- [ ] An item marked resolved has been checked against `beyond-the-fix`,161 not just marked done because a fix exists.
Run npx get-skill add annatchijova/debt-closure-discipline in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Priority determines resolution order, not permission to accumulate indefinitely — every known issue (bug, inconsistency, TODO, workaround, deferred P3) must terminate in resolved, explicitly rejected with a reason, or documented as an open unresolved constraint, never silently vanish by being written down. Use whenever triaging bugs/findings/technical debt, prioritizing a backlog, closing a task under time pressure, or reviewing whether a TODO/workaround/deferred item has actually been addressed. Trigger on "P0/P1/P2/P3", "backlog", "leave this for later", "known issue", "TODO", "technical debt", "we'll clean this up eventually", "out of scope for now". A module whose patch history has become hard to read triggers software-archaeology's replacement procedure, not a repeat of it here — see below. It is listed under Product & Planning on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
annatchijova (@annatchijova) published this skill. Their other Agent Skills are listed on their SkillMD profile.