Skip to content
sdlc

/sdlc:principle-review

Generated from solutions/ontological/skills/principle-review/SKILL.md.

Description

Section titled “Description”

Walk every principle under docs/planning/principles/ and scan the project for contradictions — code, docs, or conventions that violate a principle, and principles that contradict each other. Fans out one subagent per principle via the Workflow tool and writes an HTML report to .sdlc/reports/. Read-only on the project; the report file is the only write.

Source

Section titled “Source”

principle-review

Section titled “principle-review”

Review the project against its own principles. Output: an HTML report at .sdlc/reports/principle-review-<YYYY-MM-DD>.html plus its validated-JSON sidecar (gitignored runtime output — never committed), rendered through sdlc report render from a schema-contracted payload.

Steps

Section titled “Steps”

  1. Enumerate. List docs/planning/principles/*.md; skip closed/retired ones.

  2. Fan out — one subagent per principle via the Workflow tool. Each agent reads its principle file, then searches the project — code, skills, docs, schemas, conventions — for places that contradict or undercut it. Structured findings only: {file, evidence (quote or line), why it contradicts, severity: clear-violation | tension | drift}. Every finding cites a real location; no speculation.

  3. Cross-principle pass. One agent reads all principles together and flags pairs that contradict or materially overlap each other.

  4. Synthesize. Merge, dedupe, drop weak findings.

  5. Match against outstanding work. For each open finding, fan out (grouped by principle) to search the non-closed tasks (docs/planning/tasks/, status not closed/*) for ones whose completion would resolve the violation — confirm by reading the candidate task, never by title alone. Record them in a Tracked by column (task ids; empty = untracked gap).

  6. Write the report. Assemble the findings into a JSON payload per the contract in ${CLAUDE_PLUGIN_ROOT}lib/model/entities/principle/reports/review/schema.ts (meta header, principlesReviewed, top issues, cross-principle pairs, findings rows with Tracked by; severity tallies are derived — don’t compute them), then follow the render recipe in ${CLAUDE_PLUGIN_ROOT}conventions/skill-reports.md:

    ${CLAUDE_PLUGIN_ROOT}cli/sdlc report render principle-review <payload.json>

  7. Report. Give the user a clickable file:// link to the rendered HTML report (plus the JSON sidecar path), the three most material issues, and which open findings are untracked by any task — then continue the conversational summary.

Notes

Section titled “Notes”
  • Read-only on the project; the report artifacts are the only writes.
  • .sdlc/ is gitignored — reports are runtime artifacts, never committed.
  • Schema-contracted reports. See ${CLAUDE_PLUGIN_ROOT}conventions/skill-reports.md — this skill’s kind slug is principle-review; never hand-write the report HTML.