AgentSkillsCN

verify-and-health

运行全部五道验证关口与健康检查，针对失败情形给出可操作的修复建议，并在修复完成后再次进行验证。可在会话开始时、提交代码之前，或在需要检查项目完整性时使用。这是一种轻量级的日常使用工作流程。

SKILL.md
--- frontmatter
name: verify-and-health
description: Runs all 5 verification gates and health checks, interprets failures with actionable fix guidance, and re-verifies after fixes. Use at session start, before commits, or whenever you need to check project integrity. Lightweight daily-use workflow.
protocol_id: PROTO-ORG-4
protocol_file: organon/protocols/PROTOCOLS.md
tools: [organon-verify, organon-health]
loads:
  - CLAUDE.md
  - book-llms/three-layer-architecture.md

Verify and Health Workflow

Implements PROTO-ORG-4 from organon/protocols/PROTOCOLS.md. Daily-use verification and health check for project integrity.

When to Use This Skill

Use this skill when:

  • •Starting a work session — baseline integrity check
  • •Before committing changes — ensure nothing is broken
  • •After significant edits — verify no regressions
  • •Diagnosing issues — understand what's wrong and how to fix it

Purpose: Run all automated verification gates, interpret results, and guide fixes with specific actions.

Context Loading

  1. •Load project constraints:
    • •Read CLAUDE.md (project invariants and development workflow)
  2. •Load verification reference:
    • •Read book-llms/three-layer-architecture.md (Verification Gates section only)

Note: This is intentionally lightweight. Only load additional context if a specific failure requires it.

Steps

Step 1: Run All Verification Gates

bash
cd packages/tools && npx organon verify

This runs all 5 gates:

  • •frontmatter — YAML frontmatter present, valid, and truthful
  • •references — File paths and cross-references resolve
  • •triplets — Protocol↔workflow bindings are bidirectional
  • •coverage — Invariant coverage tracked
  • •workflow-quality — Workflows have protocol_id, tools, loads, error recovery

Step 2: Run Health Check

bash
cd packages/tools && npx organon health

Reports overall project health score with breakdown by category.

Step 3: Interpret Failures

Map each failure to a fix action:

GateDiagnostic CodeFix Action
frontmatterMissing required fieldAdd field per book-llms/frontmatter-system.md schema
frontmatterCount mismatchUpdate invariants_count, principles_count, or heuristics_count to match actual content
frontmatterToken estimate offRecalculate using ~12 tokens/line heuristic
referencesBroken file pathUpdate path to correct location or create missing file
referencesBroken related_files entryFix path or remove stale reference
tripletsOrphaned workflowAdd protocol_id and protocol_file to workflow frontmatter
tripletsPhantom automationCreate the workflow that the protocol references, or change protocol to manual tier
tripletsProtocol↔workflow ID mismatchAlign protocol_id in workflow with id in protocol
coverageInvariant without testCreate tier-4 test mapping invariant ID to test
workflow-qualityWORKFLOW_MISSING_PROTOCOL_IDAdd protocol_id: PROTO-SCOPE-N to workflow frontmatter
workflow-qualityWORKFLOW_MISSING_PROTOCOL_FILEAdd protocol_file: path/to/PROTOCOLS.md to workflow frontmatter
workflow-qualityWORKFLOW_MISSING_TOOLSAdd tools: [tool-list] to workflow frontmatter
workflow-qualityWORKFLOW_MISSING_LOADSAdd loads: array with organon files to load
workflow-qualityWORKFLOW_BROKEN_LOADS_REFFix path in loads array to point to existing file
workflow-qualityWORKFLOW_NO_ERROR_RECOVERYAdd ## Error Recovery section with failure/recovery table

Step 4: Guide Fixes

For each failure:

  1. •Identify the specific file and field
  2. •Show the exact value to add or change
  3. •Reference the specification that defines the correct format

Step 5: Re-verify

After all fixes are applied:

bash
cd packages/tools && npx organon verify && npx organon health

All gates should pass. Health score should be equal to or higher than before.

Verification

  • • All 5 gates pass (organon verify exits 0)
  • • Health score reported (organon health completes)
  • • No regressions from previous health score
  • • All fix actions were specific and actionable

Error Recovery

FailureRecovery Action
organon verify command not foundBuild organon-tools: cd packages/tools && npm install && npm run build
Gate failure not in diagnostic tableRead the gate's error message for file:line details. Check book-llms/workflow-authoring.md for diagnostic codes.
Fix introduces new failureRe-run full verification. Cascading failures are common when fixing references — fix in dependency order (frontmatter → references → triplets).
Health score decreased after fixesInvestigate what changed. A lower score usually means a file was removed or frontmatter was invalidated.
Too many failures to fix in one sessionPrioritize: frontmatter gate first (other gates depend on it), then references, then triplets, then workflow-quality.