Imported from daishiman/harness-dev (
plugins/system-spec-harness/skills/assign-system-spec-completeness-evaluator/SKILL.md). Install upstream withnpx skills add daishiman/harness-dev --skill assign-system-spec-completeness-evaluator. Copyright stays with the author.
assign-system-spec-completeness-evaluator
Runtime root contract
runtime_root_policy: host-skill-pathを適用する。- Claude Codeでは
CLAUDE_PLUGIN_ROOTをplugin rootとして使用する。 - Codexではホストが提示したこの
SKILL.mdのabsolute pathから、plugin manifestを持つ祖先を上方探索して論理PLUGIN_ROOTを解決する。 cwdからplugin rootを推測せず、literal placeholderをshellへ渡さない。各shell invocation内で解決済みabsolute pathをPLUGIN_ROOTに設定する。prompts/配下はこのowner Skill契約を継承する。
生成された仕様書ドキュメントセットを、上位概念trace / 意思決定根拠 / マトリクス網羅性 / deep knowledge目的適合 / 最新出典 / prompt品質の観点で評価し、観点別スコア + 総合判定 (PASS/FAIL) + 不足事項一覧を返す independent evaluator。
context:forkで生成者と評価者を分離する。
Purpose & Output Contract
入力: system-spec/*.md + index (C03 出力) / spec-state.json (C01) / fetched-references.json (C02)
出力: 評価レポート (schemas/completeness-findings.schema.json 準拠) — 観点別スコア + 総合判定 + 不足事項一覧
完了条件: 全観点 verdict 付与 + findings[] (info 以上を最低 1 件) + 総合判定が観点スコアからの fail-closed 再導出値と一致 + 総合 FAIL 時は不足事項一覧が非空。
各 skill 単独では見えない全体網羅性の欠落を、生成物から独立した context で評価し客観的合否を返す。
監査 sub-agent 対応 (全 6 観点中、sub-agent 関与が判定に効く 3 観点)
本 skill は全 6 観点 (上位概念trace / 意思決定 / マトリクス網羅性 / 設計知識反映 / 最新ドキュメント出典 / prompt品質) を採点する (schema/rubric/aggregate-completeness の正本)。うち foundation_trace / decision_guidance / prompt_quality は C05 R1-score の自前評価。以下は監査 sub-agent の関与が判定に効く 3 観点の対応表。
| 観点 (aspect id) | ラベル | 評価主体 (component) | 一次根拠 |
|---|---|---|---|
matrix_coverage |
マトリクス網羅性 | system-spec-matrix-auditor (C07) + sub-input system-spec-hearing-auditor (C06) |
validate-coverage-matrix.py --require-complete の exit0 + 意味層。C06 の 4 軸 (聞き漏れ/誘導/早期停止/トレーサビリティ) を網羅性・トレースの補助根拠に併せる |
design_knowledge_reflection |
設計知識反映 | C05 R1-score が自前評価 (独立 auditor なし) | 機械層=各章の設計知識ポインタ存在 (compile 注入) + 意味層=そのポインタ原則の確定セルへの具体適用 (存在確認だけで PASS にしない = Goodhart 防止) |
doc_freshness |
最新ドキュメント出典 | system-spec-doc-freshness-auditor (C08) |
二層監査 (形式=validate-source-citation.py / 内容鮮度=公式再照合) |
system-spec/*.mdを読まない C06 (hearing-auditor) を設計知識反映へ束縛するのは虚偽対応のため撤去した。C06 はヒアリング品質を担い matrix_coverage の sub-input へ再配置し、設計知識反映は C05 が system-spec/*.md と resource-map から自前評価する。監査 sub-agent (C07/C08 と matrix sub-input の C06) は Task tool でそれぞれ独立 context (fork) に起動する (R2-delegate)。監査ロジックは各 agent の SSOT prompt に委ね、本 skill は結果を集約するだけで書き換えない。
知識グラフ / doctrine の追加評価次元 (C13-C16)
上位 6 観点の top-level 構造 (aggregate-completeness.py の 6 aspect fail-closed 集約) は不変。C13-C16 の知識グラフ / doctrine 要件は新 aspect を増やさず、既存 aspect の追加評価次元として折り込む (各
validate-knowledge-graph.py --profile ...の exit0 を機械層、生成物への反映を意味層で採点)。
| 追加次元 | 折込先 aspect | 機械層ゲート | 意味層で拾う失敗 |
|---|---|---|---|
| C13 知識カタログが typed 辺グラフ | design_knowledge_reflection | validate-knowledge-graph.py --profile knowledge exit0 (循環/dangling/孤立/root到達不能 0) |
knowledge-catalog の depends_on/refines/conflicts_with 型則違反・孤立 node の設計知識への未接地 |
| C14 elicit/compile が同一 topo_order で知識消費 | design_knowledge_reflection | 上記 --profile knowledge --order の topo_order を C01 R5 / C03 R2 が同一順で消費 |
上位概念→下位概念の位相順を破って下位技術を先に確定した章 |
| C15 doctrine anchor 1正本 + 全 category 写像全射 | design_knowledge_reflection | validate-knowledge-graph.py --profile doctrine exit0 (7 concern の concern_id 一意 + 各 authority 非空・全 category→concern 写像全射。authority は 4 種で concern 間共有可・authority 一意性は非検査) |
生成章に concern authority (Apple HIG/Clean Arch/OWASP/SRE) の上流指針が具体反映されず汎用ポインタ止まり |
| C16 必須情報カタログの被覆 + block ゲート | matrix_coverage | validate-knowledge-graph.py --profile required-info exit0 (全 in-scope domain 被覆・item 最低形状・収集順序・coverage certificate) |
missing_effect=block の item 未回答のまま confirmed に進んだ確定セル (C01 R5 収集ゲート素通り。機械層ゲート validate-knowledge-graph.py (component C14) は blocking_items 列挙のみで runtime 施行せず・決定論 writer 施行は follow-up) |
C15 の意味層は「存在確認だけで PASS にしない」= design_knowledge_reflection の Goodhart 防止と同一原則で、doctrine anchor が確定セル要件へ具体適用されているかを照合する。C16 は matrix_coverage の網羅性判定に「必須情報が block ゲートを通って確定に接地しているか」を加える。
評価レポート形状 (schema)
{
"evaluator": {"name": "assign-system-spec-completeness-evaluator", "version": "0.1.0", "context": "fork"},
"verdict": "PASS" | "FAIL",
"aspects": {
"foundation_trace": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"decision_guidance": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"matrix_coverage": {"verdict": "PASS|FAIL|INDETERMINATE", "auditor": "system-spec-matrix-auditor", "component": "C07", "summary": "...", "evidence": [...]},
"design_knowledge_reflection": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...},
"doc_freshness": {"verdict": "...", "auditor": "system-spec-doc-freshness-auditor", "component": "C08", "summary": "...", ...},
"prompt_quality": {"verdict": "...", "auditor": "assign-system-spec-completeness-evaluator", "component": "C05", "summary": "...", ...}
},
"gate_results": [ {"id": "G-matrix", "name": "validate-coverage-matrix", "exit_code": 0, ...} ],
"findings": [ {"severity": "high|medium|low|info", "bucket": "...", "observation": "...", "suggested_fix": "..."} ],
"gaps": [ "不足事項1", ... ]
}
総合判定 (fail-closed 集約)
- 全観点PASS かつ high severity finding 0 件のときだけ総合 PASS。
- 1 観点でも FAIL/INDETERMINATE、または high finding が 1 件でもあれば総合 FAIL。
- 全観点を過不足なく評価していなければ総合 FAIL (監査観点の取りこぼしを PASS にしない)。
- 総合判定は
scripts/aggregate-completeness.pyのaggregate_verdictで再導出でき、レポートのverdictと一致すること (総合判定が観点スコアに接地しているかの整合検査 = Goodhart 防止)。
Key Rules
- context:fork 必須: 生成側 (elicit/doc-fetch/compile) の「網羅できた」自己肯定バイアスを断つ。
- proposer ≠ approver: 評価者は仕様書を書き換えない (read-only)。修正は elicit/doc-fetch/compile への差し戻し (Goodhart 防止)。
- 決定論ゲート優先: マトリクス網羅性は
validate-coverage-matrix.pyの exit code を一次根拠にし、自然言語で PASS 判定しない。 - 空 findings 禁止: PASS 時も info severity で「確認した観点」を 1 件以上残す。
- 総合 FAIL は差し戻し材料付き: gaps (不足事項一覧) を非空にし、どの skill (elicit/doc-fetch/compile) または監査再実行へ戻すかを記す。
Steps
正本責務は prompts/R1-score.md (スコアリング) と prompts/R2-delegate.md (監査 fork 集約)。要約:
Step 1: 観点別監査を独立 context で集約 (R2-delegate)
Task tool で監査 sub-agent (system-spec-matrix-auditor (C07) / system-spec-hearing-auditor (C06) / system-spec-doc-freshness-auditor (C08)) をそれぞれ fork する。C07 は matrix_coverage、C08 は doc_freshness の一次根拠。C06 はヒアリング品質を監査し matrix_coverage の sub-input として併せる。design_knowledge_reflection は独立 auditor を立てず Step 3 で C05 自身が評価する。
Step 2: マトリクス網羅性の決定論ゲート
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/validate-coverage-matrix.py" --matrix <spec-state.json> --require-completeexit0 をマトリクス網羅性観点の一次根拠にする (scripts/aggregate-completeness.py --matrix ... でも回収可)。
続けて C13-C16 の機械層ゲートを python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/assign-system-spec-completeness-evaluator/scripts/aggregate-completeness.py" --knowledge-graph (出荷 3 カタログを validate-knowledge-graph.py の knowledge/doctrine/required-info/cross 4 profile で独立再実行) の全 exit0 で確認する。C13/C14/C15 は design_knowledge_reflection (Step 3)、C16 は matrix_coverage の追加評価次元として意味層採点に併せる。
Step 3: 設計知識反映の自前評価 (独立 auditor なし)
C05 R1-score が system-spec/*.md 各章を直接読み、ref-system-design-knowledge/references/resource-map.yaml 由来の設計知識ポインタの (1) 存在 (機械層) と (2) その原則が確定セル要件へ具体適用されているか (意味層) を評価する。存在確認だけで PASS にしない (compile が機械注入するポインタを自己循環で肯定しない = Goodhart 防止)。汎用ポインタ (resource-map 索引) のみで具体適用が無い章は medium 以上で拾う。C06 のヒアリング品質監査は本観点でなく matrix_coverage の sub-input として使う。
Step 4: レポート出力と整合検査
schemas/completeness-findings.schema.json 準拠で評価レポートを出力。scripts/aggregate-completeness.py --report <report.json> で形状 + 総合判定整合 (fail-closed 再導出との一致) を検証する。
Gotchas
- 観点↔評価主体を取り違えない (マトリクス=C07 + C06 ヒアリング品質 sub-input / 設計知識=C05 自前評価・独立 auditor なし / 出典鮮度=C08)。C06 は system-spec/*.md を読まないため設計知識反映へ束縛しない。
- 決定論ゲート exit0 でも、意味層 (対象外理由の具体性 / 非公式 host / 設計知識反映の形骸化) で FAIL にしうる。
- high severity が 1 件でもあれば総合 FAIL。
- INDETERMINATE は fail-closed で FAIL に寄せ、仕様書修正でなく監査再実行/入力補完へ差し戻す。
- 本 skill は kind=assign のため feedback_contract.criteria は N/A (評価器自身は評価基準を携帯せず、checklist 観点 + evaluator ゲートで担保。frontmatter の skip_reason 参照)。
Additional Resources
references/scoring-rubric.json— 全 6 観点機械判定ルールと fail-closed 集約ポリシーreferences/aspect-criteria.md— 観点別意味判定の詳細基準 + 観点↔監査 agent 対応schemas/completeness-findings.schema.json— 評価レポート出力スキーマscripts/aggregate-completeness.py— レポート形状検証 + 総合 fail-closed 集約 (決定論)prompts/R1-score.md/prompts/R2-delegate.md— R1 (スコアリング) / R2 (監査 fork 集約) 責務正本- fork 先 agent:
../../agents/system-spec-{matrix,hearing,doc-freshness}-auditor.md