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