| name | necessity-audit |
| description | Necessity audit for over-designed spec elements. Use when: auditing lifecycle spec (1-requirements / 2-tech-spec / 3-architecture) for YAGNI/KISS violations, challenging necessity of FRs/NFRs/abstractions/configs via Codex adversarial debate. Not for: FP reasoning validity (use /codex-review-spec), completeness check (use /feature-completeness), detail review (use /codex-review-doc), or code-level simplification (use /simplify). |
| allowed-tools | Read, Grep, Glob, Write, Bash(git:*), Bash(node:*), Bash(wc:*), Bash(mktemp:*), Bash(rm:*), mcp__codex__codex, mcp__codex__codex-reply |
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 templatereferences/phase-b-debate-topic.md — Phase B topic builder documentationreferences/phase-c-consolidate.md — Phase C logicreferences/output-template.md — Markdown report layoutreferences/review-loop.md — --continue flowreferences/redaction-rules.md — Secret / PII patterns applied by redact.js
Verification
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
