Skip to content

EVALUATION.md

Latest commit

 

History

History
70 lines (59 loc) · 6 KB

EVALUATION.md

File metadata and controls

70 lines (59 loc) · 6 KB
intent_id INT-001
owner your-handle
status active
last_reviewed_at 2026-04-09
next_review_due 2026-05-09

Evaluation

Acceptance Criteria

  • docs/requirements.md、docs/spec.md、docs/design.md、docs/CONTRACTS.md が repo 実態と矛盾しないこと。
  • Birdseye / Codemap の更新手順が README.md、docs/BIRDSEYE.md、docs/birdseye/README.md、GUARDRAILS.md、RUNBOOK.md で整合していること。
  • docs/CONTRACTS.md に定義された .ga/qa-metrics.json と governance/predictor.yaml の feature detection 契約が維持されていること。
  • PR本文に Priority Score（値と根拠）が記録されていること。
  • PR本文から docs/acceptance/AC-YYYYMMDD-xx.md 形式の検収記録へ遷移できること。
  • docs/acceptance/ 配下の検収記録が front matter と必須見出しを満たしていること。
  • governance/policy.yaml の forbidden_paths を無断で変更しないこと。
  • インシデント発生時は docs/IN-YYYYMMDD-XXX.md を作成し、該当 PR および RUNBOOK.md から相互リンクすること。
  • 単体テストと結合テストの対象が Task Seed または検収記録に記載されていること。
  • Python 系の変更では coverage 80% 以上を確認すること。
  • 最低限の回帰確認として、次のテストが通ること。
    • tests/test_codemap_update.py
    • tests/autosave/test_project_lock_service.py
    • tests/merge/test_precision_mode_pipeline.py
    • tests/test_collect_metrics_cli.py
    • tests/perf/test_collect_metrics_autosave_merge.py

KPIs

指標 目的 収集方法 目標値
checklist_compliance_rate ドキュメント出荷時に必須チェックリストへ準拠できた割合を可視化し、ヒューマンエラーの早期検知につなげる。 python -m tools.perf.collect_metrics --suite qa --metrics-url <Prometheus URL> --log-path <StructuredLogger 等の運用ログ> で .ga/qa-metrics.json を生成し、checklist_compliance_rate を参照する。必要に応じて構成管理ログ（例: docs/logs/docops.log）で完了数と対象総数を突合する。詳細は RUNBOOK.md#Observability。 週次平均で 0.95 以上。
task_seed_cycle_time_minutes Task Seed の受付から初回処理完了までの所要時間を把握し、着手遅延を抑制する。 .ga/qa-metrics.json に正規化される task_seed_cycle_time_* 系イベントを参照する（収集 CLI は RUNBOOK.md#Observability に準拠）。 1440 分（24 時間）以下を維持。
birdseye_refresh_delay_minutes Birdseye ダッシュボードの更新遅延を監視し、情報可視化の鮮度を保証する。 Prometheus の birdseye_refresh_delay_* 系メトリクスを CLI が平均化し .ga/qa-metrics.json に書き出す。必要に応じてジョブ監視ログで遅延の有無を確認する。 60 分以下を維持。
review_latency レビュー待機時間を定量化し、ボトルネックを可視化する。 Prometheus の workflow_review_latency_* / legacy_review_latency_* を CLI が正規化した値を .ga/qa-metrics.json から取得する。詳細は RUNBOOK.md#Observability。 12 時間以下を維持。
compress_ratio トリミング後コンテキストの圧縮率を測定し、情報損失を防ぐ。 tools.perf.metrics_registry.MetricsRegistry.observe_trim を通じてエクスポートし、収集 CLI が .ga/qa-metrics.json に書き出した値を確認する。 0.60 以下を維持し、過剰圧縮を回避。
semantic_retention コンテキストトリミング後に保持された意味情報の割合を監視し、質の劣化を検知する。 埋め込みログ（例: StructuredLogger 経由の semantic_retention）を CLI が統合し .ga/qa-metrics.json へ出力する。手順は RUNBOOK.md#Observability を参照。 0.85 以上を維持。
reopen_rate 再オープン率を追跡し、運用完了後の手戻りを抑制する。 Prometheus の workflow_reopen_rate_* → docops_reopen_rate → reopen_rate を収集 CLI が正規化し .ga/qa-metrics.json に出力する。 5% 以下を維持。
spec_completeness スペック充足率を定量化し、要求事項の欠落を防ぐ。 Prometheus の workflow_spec_completeness_* と運用ログ（例: StructuredLogger の spec_completeness_*）を CLI が統合し .ga/qa-metrics.json で欠損や乖離を確認する。 90% 以上を維持。

KPI の収集手順と CLI オプションは常に RUNBOOK.md#Observability と同期し、差異があれば双方を更新する。

Test Outline

  • 単体:
    • tests/test_codemap_update.py
    • tests/autosave/test_project_lock_service.py
    • tests/merge/test_precision_mode_pipeline.py
  • 結合:
    • tests/test_collect_metrics_cli.py
    • tests/perf/test_collect_metrics_autosave_merge.py
  • coverage:
    • pytest --cov=. --cov-report=term-missing --cov-fail-under=80
  • 補助シナリオ:

検証手順の詳細は docs/addenda/I_Test_Cases.md を参照する。

Verification Checklist

  • requirements / spec / design / CONTRACTS の整合を確認した
  • Birdseye / Codemap の更新導線が関連文書で一致している
  • 最低限の回帰テスト結果を確認した
  • 単体テスト / 結合テスト / coverage 80% の結果を確認した
  • 検収記録を docs/acceptance/ に作成し、PR から参照できる
  • エラー時挙動と feature detection 契約が明示されている