justify
Judges, on evidence, whether one named artifact (a file, doc section, dependency, component) had and still has a reason to exist, or whether a proposal (a plan step, design option, or mechanism to add) is needed at all. Read-only. Use when the user asks whether a thing needs to exist or still earns its keep, or of a proposal whether it is overengineered, whether we need X, or whether there is a simpler way. Not for the enforcement surface (overengineering:audit).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- shell
- bash
- metadata
- { "summary": "Make one artifact, or one proposal before it is built, justify its existence on evidence", "workflow-stage": "anytime" }
- description
- Judges, on evidence, whether one named artifact (a file, doc section, dependency, component) had and still has a reason to exist, or whether a proposal (a plan step, design option, or mechanism to add) is needed at all. Read-only. Use when the user asks whether a thing needs to exist or still earns its keep, or of a proposal whether it is overengineered, whether we need X, or whether there is a simpler way. Not for the enforcement surface (overengineering:audit).
- argument-hint
- [path|path#heading|kind:identifier|proposal]
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 2
- 参考文档context/planned-mode.md4.2 KB
- 参考文档evals/evals.json28.1 KB
03 SKILL.md 正文
Arguments. [path|path#heading|kind:identifier|proposal]. A proposal runs planned mode. none: conversation context, then offered git-age discovery, then ask
Repository context. Gather first
Run this as its own Bash call, never combined with another command:
- Branch,
git symbolic-ref --quiet --short HEAD
It prints the branch on stdout, or fails with no output on a detached checkout or outside a repository. Read the exit status to decide whether there is a branch, and take the name from stdout. Treat a failure (not a repository, git unavailable) as an unknown value and carry on.
Purpose
Point at one artifact and test two things: a reason existed when it was built, and that reason
still holds. Read ${CLAUDE_PLUGIN_ROOT}/context/scrutiny-method.md before judging anything and cite
its sections; every bare §N here is one of them. Read
${CLAUDE_PLUGIN_ROOT}/context/justification-lane.md before the first target: it holds this lane's
item inventory, its five layers and probes, its evidence sources, protected classes, routing
precedence and known limits, cited here as "lane section N".
A proposal, something not yet built, takes planned mode instead (section "Planned mode").
Report the verdict first, then discuss. The operator decides refactor or remove; the owner the finding names carries it out, never this skill.
Read-only contract
${CLAUDE_PLUGIN_ROOT}/skills/audit/SKILL.md, section "Read-only contract", governs. Specific to
this lane:
- The only write of its own is the findings artifact, at the home
${CLAUDE_PLUGIN_ROOT}/context/findings-artifact.md"Where it lives" defines; never the artifact being judged. Right after resolving the home, emit the read-only opening line naming that home as where a finding would be written, since this run may file no row. The self-ignore guard still runs. - Always
mode: targeted, withtargetsnaming what this run examined. Nevermode: walk. - Frontmatter:
type: overengineering-findings(first; consumers select on it),schema: 2,mode: targeted,targets, this run'sdateandbranch, andscopecarrying the prior value forward with these targets' layers added. An on-diskschemaother than1or2stops the run with a visible message; aschema: 1artifact is merged into and rewritten at2. - Re-read before write. Load the on-disk artifact immediately before writing, merge against that
copy, and check its
datefor another producer's write during this run. - A run that filed no row writes no artifact, however it got there: the ladder ended at an offer or a question, every target routed away, every target was declined as an ambiguous heading, or anything else. Emit the inline report in full, naming the rung, the routing or the collision.
A detached checkout has no branch identity
${CLAUDE_PLUGIN_ROOT}/skills/audit/SKILL.md, section "A detached checkout has no branch identity",
governs: prefer a logical ref the environment supplies, normalized and validated as a branch name;
otherwise persist nothing and say, in these words:
detached checkout, no logical ref supplied; no branch identity, so no findings artifact is written
The pass still runs and the inline report is emitted in full; only the persisted write is declined.
Arguments
Parse $ARGUMENTS as one target:
| Form | Meaning |
|---|---|
| A path | a file, or a directory as one item |
path#heading |
one section of a file, identified by its full heading ancestry |
| A kind-prefixed identifier | an item with no path, such as a package |
path:line, or a comment |
accepted, then widened per the rule below |
| A proposal: a plan step, a design option, or text describing what to add | planned mode |
A proposal is text that describes something to add rather than naming an existing artifact. A
free-text proposal is never parsed as a path or a kind:identifier; where an argument could be
either, confirm the reading in one line before judging.
An ambiguous heading is declined, never disambiguated. Where the full ancestry of a
path#heading target is not unique in the file, decline the target, name the collision, and ask for
a whole-file target or a disambiguating rename. Never fall back to the first occurrence or an
occurrence count: the next edit renumbers them and the item derives a different id
(${CLAUDE_PLUGIN_ROOT}/context/findings-artifact.md, "Finding ids").
A line or comment target widens (lane section 2): to the enclosing heading where the file has
headings, to the file otherwise. State the widening in the report's first line: what was pointed
at, what is judged instead, and that an id resting on a line number changes when an edit above moves
it. For a comment, name code-tidying:remove-comments as the owner of comments in that line.
No target: the ladder in lane section 10. It never sweeps. State which rung was used.
-
Conversation context. Where the session has been discussing an artifact, or a proposal not yet built, infer it and confirm the inference in one line before walking or judging.
-
Offer git-age discovery, and wait. Describe what it would rank; run it only on an answer:
git log --diff-filter=A --name-only --format='%ad' --date=short -- . | awk 'NF'Post-process into (path, first-seen date) pairs, oldest first: a candidate list, never a finding set. Age is not evidence of disuse (lane section 10): check each ranked path for inbound references under lane section 7's varied query forms, counting citations from anywhere in the repository including the path's own directory, and drop any that have one. Present the survivors with both counts, ranked and surviving.
-
Ask what to point at.
Planned mode
A proposal has nothing built to judge, so the artifact sections ("Read-only contract", "Before the
walk", "The walk", "Verdicts and evidence", "Intent checkpoints", "The report") do not apply to
it. Planned mode resolves no home, runs no preflight or routing test, emits no §6 token and writes
no findings artifact: a finding id derives from an artifact's identity (findings-artifact.md "Finding ids"),
and a proposal has none. The no-mutation rule of ${CLAUDE_PLUGIN_ROOT}/skills/audit/SKILL.md
"Read-only contract" still governs: planned mode writes nothing at all and builds none of what the
proposal describes. Read
${CLAUDE_PLUGIN_ROOT}/skills/justify/context/planned-mode.md and run its test, then report inline:
each mechanism's verdict first, then the option with the fewest moving parts, then discussion. The
closing line says nothing was persisted.
Before the walk
- Resolve the branch identity, then the home, as
${CLAUDE_PLUGIN_ROOT}/skills/audit/SKILL.md"Before the walk" step 1 does. Never infer an identity from a failed call, and never accept the literalHEAD. Compose the home perfindings-artifact.md"Where it lives". - Run the shared preflight,
${CLAUDE_PLUGIN_ROOT}/skills/audit/context/surface-walk.md"Preflight". A repetition a record sanctions and a check maintains is never duplication to collapse. - Add the lane's four preflight items (lane section 7): vary the query form before any absence claim, make a retirement cost more than a keep, write targeted mode, re-read before write.
- Apply the routing test (lane section 1) before classifying. A target an enforcement probe
inventories whole routes to
/overengineering:auditand writes no row; a target only partly inventoried is classified with the routed part named inRouted-to. - Resolve consumer configuration and load the prior artifact, as the sibling does. Write
Status: OPENon a finding not seen before and carry every other status forward. Surface any verdict that moved under a carried-forward judgment (merge rule 5): a direction flip, or a same-direction change to what the acceptance authorized. No consumer re-derives that flag, so a move this step misses goes unreported.
The walk
One target is one item, unless the container rule in
${CLAUDE_PLUGIN_ROOT}/skills/audit/context/surface-walk.md "Granularity" splits it into
mechanically listed members. Run that document's "The per-layer loop" once: identify, classify,
answer the three liveness questions independently (§3), reconstruct intent (§4), rediscover (§5),
weigh cost (§1, §6), verdict (§6), owner (§12), write.
Verdicts and evidence
Every verdict is one of §6's six tokens, argued in carry cost (§1), and cites at least one empirical source or is UNPROVEN naming the tier consulted and whether it was silent or unavailable (§2). Every row also carries:
Basis, perfindings-artifact.md"Per-finding fields":unexaminedwith UNPROVEN when nothing was measured (no tier consulted, or every consult silent or unavailable) and nothing else carries the verdict;class-inferredwhere the verdict rests on the non-derivable oracle or a protected-class match (lane section 9). A KEEP ismeasuredor it is not a KEEP.Ablation: n/a, because that gate does not apply on this lane's layers (lane section 8). The earned-keep gate is the one every row answers; fusing a class claim with an earned-keep verdict is a defect. Thecheckconstituent of every id carriesjustifyas its producer segment.
Intent checkpoints
Attended only. Report first, then discuss. Where intent scores MEDIUM or LOW (§4), or tiers 1 to
3 are silent and tier 4 could exist, ask before writing UNPROVEN: recommendation first, one small
numbered set of questions, batched. Use planning:interview's mechanics where installed, otherwise
ask inline. "I don't know" is accepted: it records UNPROVEN with the tier named.
Boundary
This lane reports and hands off. Each route is presence-gated: where the plugin is absent, say so,
state what it would have owned, and record the fallback in Routed-to.
| The finding is about | Owner |
|---|---|
| The enforcement surface, whole | overengineering:audit |
| Unreachable or dead code | code-tidying:audit-dead-code |
| Comments, their content or residue | code-tidying:remove-comments |
| A document derivable from its source, or noise within one | docs-hygiene:audit-derivability, docs-hygiene:audit-noise |
| Instruction text and what it does to a model | harness-config:audit-instructions, harness-config:unhobble |
| Duplication of a native harness surface | harness-ops:audit-native-overlap |
| Ranking candidates across several dimensions | improvement:find |
| The scrutiny posture itself | discipline:reason-dont-recite, discipline:recheck-against-upstream, discipline:scrutinize-dont-coast |
Executing a finding belongs to overengineering:realign, which presents this lane's rows and offers no rung for them until a ladder for
these layers exists. Name it as the next
step and never start it unasked.
The report
${CLAUDE_PLUGIN_ROOT}/skills/audit/context/report-template.md owns the shape. For this lane: a
widened target puts the widening in the first line; a routed target is reported inline with the
layer that claimed it and no row. The artifact is not written with no branch identity or when no row
was filed, so the opening line names the resolved home without asserting a write, and the closing
summary states whether anything was persisted.
Next
- Findings filed on an artifact: /overengineering:realign.
- A proposal judged: /planning:plan.
Gotchas
- A single grep is not a search. A phrase wrapped across a line break defeats a single-line match. Vary wrapping, hyphenation, casing and obvious synonyms before "not found" becomes a finding, and record the forms tried.
- Relocated coverage is not absent coverage. A guard that never fires because its concern is now handled earlier is not an unguarded concern. Find where the concern went; the finding is then about the duplicate, argued on carry cost.
- Silence about a document is usually unavailable, not empty. Most consumers record nothing about which documents get read, so no usage data means tier 1 does not exist here (§2).
- A class match is a marker, never a verdict. "It is a decision record" says which rules apply, not whether this one earns its keep.
- The operator's framing is not evidence. A target arriving with its conclusion attached ("this is duplication", "retire it") is a hypothesis to test.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').