todo-guardian

TODO Guardian

Wrong skill? Creating TODOs → todo-management. Planning → plan-and-execute. Completion retrospective → see verification-before-completion Loose-Ends Retrospective section.

Announce at start: "I am using the todo-guardian skill to enforce TODO discipline."

When to Use

• The moment explicit deferral language appears in your planned output
• Before claiming completion — audit for open #loose-end items
• At natural session milestones (before commit, before completion claim, at session end)
• When reviewing session for missed action items

Deferral Language Patterns (High-Precision Only)

Capture immediately when you write any of these explicit commitment-to-defer phrases:

Pattern	Examples
Explicit future commitment	"I'll fix this later", "I'll do this later", "I'll address this later", "I'll come back to this"
Explicit skip	"let me skip this for now", "I'll do this in a follow-up"
Explicit deferral	"I need to follow up on this later", "this needs follow-up"

Do NOT capture coordination language like "for now let's use X", "we should also consider Y in a future PR", or "I noticed Z" — these are normal working speech, not deferral commitments.

Enforcement Rules

Rule 1: Capture or Block

Deferral language detected → record immediately using the enforcing wrapper:

~/.codex/superpowers-plus/tools/loose-ends.sh add \
  --desc "<what was deferred> — deferred at <context>" \
  --note "<why it can't be done now>"

loose-ends.sh add enforces --note at the shell level — it will refuse to record without a justification, so there is no way to accidentally omit it.

Dedup check first: Run loose-ends.sh check and scan for the same core item. If already present, skip — do not double-record.

NEVER allow deferral-language to pass without either (a) recording via loose-ends.sh add or (b) resolving immediately.

Rule 2: Audit at Milestones

At any natural session milestone (before a commit, at session end, before a completion claim), run the single audit command:

~/.codex/superpowers-plus/tools/loose-ends.sh check

loose-ends.sh check handles both count and note inspection in one call. Exit 0 = clean. Non-zero exit = items require review (count shown). --all is handled internally so deferred items are always surfaced.

Rule 3: Completion Gate

Before claiming any work is complete, run:

~/.codex/superpowers-plus/tools/loose-ends.sh check

• Exit 0 (clean), OR all listed items reviewed and classified
• Any must-address item is fully resolved
• Any deferred item shows a note/reason line in the output

Items with no observable justification → BLOCK completion → resolve or escalate to human.

Rule 4: Session-End Sweep

At session end, report: Created: N · Resolved: M · Deferred with justification: K

Unresolved #loose-end items persist to the next session automatically — they will surface in the next run of verification-before-completion.

---

Anti-Patterns

Anti-Pattern	Detection	Correction
Explicit deferral, no record	"I'll fix this later" → no add call	Record with --note immediately
Completion with open loose ends	Audit finds #loose-end items	Block; resolve or escalate
Missing creation-time justification	--note absent on deferred items	Cannot retrofit — escalate to human
Double-record	Same item added twice	Dedup scan before adding
Over-capture	Normal speech flagged as deferral	Check pattern table — only explicit commitment phrases trigger capture

Failure Modes

Failure	Recovery
Missed deferral	Add retroactively; note it as retroactive in --note
False positive trigger	Add phrase to anti_triggers
Blocks incorrectly	Verify items are genuinely resolved; close them

Companion Skills

• todo-management: CRUD operations
• verification-before-completion: Completion gate (Loose-Ends Retrospective section)
• plan-and-execute: Planning sequences
• quantitative-decision-gate: TODO priorities