necessity-audit

Necessity Audit

3-phase necessity audit with Codex adversarial debate. Identifies over-designed elements in lifecycle specs via 6-dimension YAGNI rubric.

Non-Negotiable Rules

SKILL.md is the normative source. Reference files elaborate but do not override.

#	Rule	Violation =
1	Phase A classification output must NOT appear in Phase B debate topic	Audit invalid
2	Phase B must invoke /codex-brainstorm via Skill tool — raw mcp__codex__codex for debate is invalid	Audit invalid
3	Phase C report must include non-empty debate.threadId	Report rejected
4	Phase C report must include Debate Conclusion referencing specific rounds (not blank / placeholder)	Report rejected
5	Output must start with ## Document Review header and end with ✅ Mergeable OR ⛔ Needs revision sentinel	Auto-loop cannot parse

Trigger

• Keywords: necessity audit, over-design, YAGNI audit, spec necessity, 過度設計, over-engineered

When NOT to Use

Alternatives by intent

Intent	Use	Not this skill
「這段推理站得住嗎？」	/codex-review-spec (planned) / /review-spec	—
「這個 spec 完成了嗎？」	/feature-completeness (planned)	—
「這個 code 是否過度抽象？」	/simplify / /refactor	—
「這個實作符合產業標準嗎？」	/best-practices	—
「這個 spec 是否過度設計？需要砍嗎？」	/necessity-audit ← this skill	—

Chain recommendation

/codex-review-doc (detail) → /codex-review-spec (reasoning, planned) → /necessity-audit (necessity, this skill) → /feature-completeness (completeness, planned) → /review-spec (synthesis)

Arguments

Arg	Required	Default	Purpose
<path>	Yes	—	Target lifecycle spec (repo-relative)
--depth brief|normal|deep	No	normal	Dimension coverage + equilibrium strictness
--continue <threadId>	No	—	Resume Phase C via mcp__codex__codex-reply
--skip-preflight	No	false	Skip state-read advisory; emits [PREFLIGHT SKIPPED] banner
--include-feasibility	No	false	Accept 0-feasibility-study.md (emits override banner)
--override <id>:<rationale>	No (repeatable, ;-separated)	—	Mark Cut element as kept with justification
--output markdown|json	No	markdown	Output format

Workflow

Phase 0 preflight → Phase A classify → Phase B Codex debate → Phase C consolidate → Redact → Emit

Phase 0: Preflight (executable)

TMPDIR=$(mktemp -d)
node scripts/skills/necessity-audit/preflight.js \
  --path <path> --depth <depth> \
  [--skip-preflight] [--include-feasibility] \
  --output $TMPDIR/preflight.json

Non-zero exit = hard block. Read $TMPDIR/preflight.json to continue.

Phase A: Claude classify (LLM)

Read target file with Read tool. Apply references/phase-a-classify.md template substituting ${TARGET_PATH}, ${DOC_KIND}, ${ACTIVE_DIMENSIONS}, ${GREENFIELD} from preflight.

Extract elements (FR / NFR / Component / Abstraction / Extensibility / Config), score each against active dimensions only (depth=brief → dims 1-3; normal/deep → dims 1-6), assign initial Keep/Review/Cut.

Write result: Write tool → $TMPDIR/phase-a.json with schema { elements: ClassifiedElement[] } (only claude.* fields populated).

Phase B: Codex debate (Skill invocation)

node scripts/skills/necessity-audit/debate-topic.js build \
  --preflight $TMPDIR/preflight.json \
  --output $TMPDIR/topic.txt

Read topic, invoke:

Skill("codex-brainstorm", <contents of $TMPDIR/topic.txt>)

Write raw response: Write tool → $TMPDIR/debate.txt.

node scripts/skills/necessity-audit/debate-topic.js parse \
  --input $TMPDIR/debate.txt \
  --output $TMPDIR/debate.json

Phase C: Consolidate (executable)

node scripts/skills/necessity-audit/consolidate.js \
  --phase-a $TMPDIR/phase-a.json \
  --debate $TMPDIR/debate.json \
  --preflight $TMPDIR/preflight.json \
  --overrides "<id>:<rationale>[;...]" \
  --depth <depth> \
  --output $TMPDIR/report.json

Applies 6 deterministic checks, under-coverage check, --override handling, gate selection.

Assemble + Redact + Emit

node scripts/skills/necessity-audit/report.js \
  --input $TMPDIR/report.json \
  --format markdown \
  --output $TMPDIR/report.md

node scripts/skills/necessity-audit/redact.js \
  --input $TMPDIR/report.md \
  --output $TMPDIR/report.final.md

Read $TMPDIR/report.final.md and emit as final user-visible message. Cleanup: rm -rf $TMPDIR.

Output Format + Gate Selection

Output header, sections, sentinel: see references/output-template.md (normative). Gate-selection decision table + narrative rules: see references/phase-c-consolidate.md.

Invariant: ⚠️ Need Human NEVER appears as the final gate — only as a narrative line above the ✅ Mergeable / ⛔ Needs revision sentinel.

Review Loop (--continue)

After user revises the spec, re-run with --continue <threadId> to reuse the Codex debate context via mcp__codex__codex-reply. See references/review-loop.md.

References

• references/dimensions.md — 6-dimension × 4-tier rubric (authoritative)
• references/phase-a-classify.md — Phase A prompt template
• references/phase-b-debate-topic.md — Phase B topic builder documentation
• references/phase-c-consolidate.md — Phase C logic
• references/output-template.md — Markdown report layout
• references/review-loop.md — --continue flow
• references/redaction-rules.md — Secret / PII patterns applied by redact.js

Verification

• Phase B used Skill("codex-brainstorm"), not raw mcp__codex__codex
• Report contains non-empty debate.threadId
• Report contains non-empty Debate Conclusion
• Output starts with ## Document Review header
• Output ends with ✅ Mergeable OR ⛔ Needs revision sentinel
• ⚠️ Need Human never used as gate (only as narrative)
• Redaction applied before emission

Examples

Input: /necessity-audit docs/features/foo/2-tech-spec.md
Action: Phase 0 preflight → Phase A classify → Phase B debate → Phase C consolidate → report + redact → emit with sentinel

Input: /necessity-audit docs/features/foo/2-tech-spec.md --continue 019dab42-xxxx
Action: Resume via codex-reply; re-run Phase C with updated spec; emit diff-focused report

Input: /necessity-audit docs/features/foo/1-requirements.md --depth brief --skip-preflight
Action: Only challenge dims 1-3; skip state advisory; emit [PREFLIGHT SKIPPED] banner

Input: /necessity-audit docs/features/foo/2-tech-spec.md --override FR-12:"needed for Q3 rollout"
Action: FR-12 kept with justification; final gate ✅ Mergeable if no other Cut items remain