no-suppression-markers

name	no-suppression-markers
user-invocable	false
description	Verify a coding change introduced no placeholder or suppression markers without explicit user permission. Covers TODO/FIXME/HACK/XXX, commented-out code, skipped or focused tests (.skip/.only/xit/fit), and silenced type/lint checks (@ts-ignore, @ts-nocheck, eslint-disable,
when_to_use	Trigger when wrapping up a coding task — before declaring it done, before a commit, when reviewing a diff, or when finalizing/auditing changed files for leftover shortcuts.

No suppression / placeholder markers

A completion gate for code changes. Reinforces the global rule "No placeholder or suppression markers in completed work" by turning it into a concrete, run-before-done check.

What counts as a marker

• Placeholders: TODO, FIXME, HACK, XXX; commented-out code left "for later".
• Stubs as pseudo-implementations — a function whose body is a stand-in (return null, return true, return {}, throw new Error("not implemented"), Python pass / raise NotImplementedError, Java return null for an unimplemented contract) used specifically as a placeholder for logic that should exist. The nuance matters: return null is legitimate when null is a valid domain result (search-not-found, optional value); it is a stub when the function's contract obligates work that has not been written. Tell them apart by intent — if the docstring / signature promises behaviour the body does not deliver, it is a stub.
• Skipped / focused tests: .skip(...), .only(...), xit, fit, xdescribe, fdescribe, @pytest.mark.skip, @unittest.skip. A focused test (.only) silently disables every other test in the file.
• Silenced checks: @ts-ignore, @ts-nocheck, eslint-disable*, # type: ignore, # noqa, pylint: disable, // nolint.

The rule

• These are not allowed in work you declare complete.
• Introducing any of them requires explicit user permission — name it, say why, and wait.
• A failing test or a type/lint error is a contract signal: surface it and discuss the fix. Silencing it hides the contract break instead of resolving it.
• Prefer self-documenting suppressions when one is genuinely justified and approved: e.g. @ts-expect-error (errors once the suppression is no longer needed) over @ts-ignore.

How to check before declaring done

Scan only the files you changed, and only source files (skip docs/config — they legitimately mention these markers):

git diff --name-only --diff-filter=d HEAD \
  | grep -Ei '\.(py|ts|tsx|js|jsx|mjs|cjs|dart|go|rb|rs|java|kt|swift|cs|cpp|c|h|scala|php|lua|sh|sql|vue|svelte)$' \
  | xargs -r grep -nE 'TODO|FIXME|HACK|XXX|@ts-(ignore|nocheck)|eslint-disable|#[[:space:]]*type:[[:space:]]*ignore|#[[:space:]]*noqa|pylint:[[:space:]]*disable|\.(skip|only)\(|\b(xit|fit|xdescribe|fdescribe)\(|\bNotImplementedError\b|throw new Error\(["'\'']TODO|throw new Error\(["'\'']not implemented'

Use --cached instead of HEAD to scan staged changes only. Adjust the extension list to the project's languages.

If markers are found

1. Resolve them — implement the deferred work, restore the skipped test, fix the underlying type/lint error.
2. If a marker is genuinely justified (e.g. an external blocker), stop and ask the user before keeping it. Get explicit permission; do not declare done with it silently in place.
3. Re-run the scan until it is clean.

Notes

• A non-blocking PostToolUse hook (plugin-dist/hooks/scripts/scan-suppression-markers.py) surfaces newly introduced markers per edit as an immediate reminder. This skill is the deliberate before-done gate — run it when finalizing, not just per edit.
• The hub's engineer agents in plugin-dist/agents/ reference this gate in their pre-done verification; any agent that finalizes or reviews code should run it before declaring done.