codd-validate

CoDD Validate

Validate CoDD frontmatter and dependency references before impact analysis so broken metadata does not poison the graph or downstream change-propagation work.

Usage

Run this skill after codd scan --path ., after editing requirement or design documents, or any time you suspect frontmatter or dependency references may be inconsistent.

Instructions

1. Preflight:

   • Work from the project root.
   • Verify codd/codd.yaml exists. If not, run codd init first.
   • If the codd command is not available, install the package so the CLI entry point is on PATH before continuing.

2. Run validation:

codd validate --path .

1. Interpret the result:

   • PASS: Treat OK: validated ... output as a pass. Frontmatter is structurally valid enough to proceed, and dependency references are consistent enough for the next step. After a clean pass, codd impact is safe to run.
   • ERROR: Stop and fix the reported documents before continuing. Use the categories below to decide the repair.
   • BLOCKED or WARNING: Read the message, fix what is actionable, and re-run validation until the remaining output is understood.

2. ERROR triage by category:

   • missing_field: Required frontmatter data is missing or malformed. Open the affected design document and add or repair the needed fields, especially node_id, title, and depends_on when the design requires declared upstream dependencies. In current validator output, this often appears as missing or invalid frontmatter rather than a literal missing_field code.
   • invalid_reference: A document references a node_id that does not exist or is misspelled. Correct the typo or point the reference at the real upstream node. In current validator output, this usually shows up as undefined-reference messages such as dangling depends_on or depended_by.
   • circular_dependency: Two or more documents depend on each other in a loop. Revisit depends_on, remove the back-edge, and restore a one-way dependency order.