/sdlc:principle-review

Generated from solutions/ontological/plugin/plugins/sdlc/skills/principle-review/principle-review.md.

Description

Walk every principle under docs/planning/principles/ and scan the project for contradictions — code, docs, or conventions that violate a principle, principles that contradict each other — and read each principle’s own text for being fully descriptive yet succinct. Fans out one subagent per principle via the Workflow tool and writes an HTML report to .sdlc/reports/. With —propose, also lands the text edits it recommends on a branch and opens one PR. Invoke for “review the principles”, “do the principles contradict each other”, “are the principles too long”, or “propose principle fixes”.

Source

principle-review

Review the project against its own principles, and the principles against the descriptive-yet-succinct bar. 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. With --propose, one PR carrying the recommended text edits.

Usage:

/sdlc:principle-review — report only; read-only on the project.
/sdlc:principle-review --propose — report, then a PR of proposed edits.

Steps

Enumerate. List docs/planning/principles/*.md; skip closed/retired ones.
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.
Cross-principle pass. One agent reads all principles together and flags pairs that contradict or materially overlap each other.
Descriptive-yet-succinct pass. One agent reads every principle’s own text against ${CLAUDE_PLUGIN_ROOT}/conventions/descriptive-yet-succinct.md. Per principle and body section it records {section, direction: under-described | over-long, evidence, fix}; the fix is the concrete edit, not a description of one.
Synthesize. Merge, dedupe, drop weak findings.
Match against outstanding work. For each open finding, fan out (grouped by principle) to search the non-closed tasks (docs/planning/tasks/, state 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).
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, proseIssues; 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>
```
Propose (only with --propose). Follow ${CLAUDE_PLUGIN_ROOT}/conventions/review-proposal-pr.md with slug principle-review and plural principles: branch, apply the text edits the findings and prose issues recommend, validate each edited entity file, commit per principle, open the PR, then add proposal to the payload and re-render the report.
Report. Give the user a clickable file:// link to the rendered HTML report (plus the JSON sidecar path), the three most material issues, which open findings are untracked by any task, and the PR URL when one was opened — then continue the conversational summary. End with the terminal marker:
```
PRINCIPLE-REVIEW-DONE report=<html path> [pr=<url>]
```

Notes

Without --propose the report artifacts are the only writes. With --propose the worktree under .sdlc/worktrees/ and the PR branch are the only other writes; the main checkout stays untouched.
.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.
Prose rubric. See ${CLAUDE_PLUGIN_ROOT}/conventions/descriptive-yet-succinct.md — the section-by-section checks step 4 applies to a principle’s Summary, Statement, Why, How it applies, Examples, and Implications.
Proposal PRs. See ${CLAUDE_PLUGIN_ROOT}/conventions/review-proposal-pr.md — text edits ride the PR; code changes stay findings, listed under Not proposed.