home / skills / duc01226 / easyplatform / why-review
This skill audits a completed feature or refactor for reasoning quality and provides an Understanding Score with gaps.
npx playbooks add skill duc01226/easyplatform --skill why-reviewReview the files below or copy the command above to add this skill to your agents.
---
name: why-review
description: "[Review & Quality] Audit completed feature/refactor for reasoning quality with Understanding Score (0-5)"
argument-hint: [optional-focus-area]
infer: true
---
# /why-review -- Understanding Verification
Audit a completed feature or refactor for reasoning quality. Produces an Understanding Score (0-5).
## Summary
**Goal:** Verify that changes were made with understanding, not just pattern compliance.
| Step | Action | Key Notes |
|------|--------|-----------|
| 1 | Gather changes | List all files changed in current session/branch |
| 2 | Reasoning audit | For each significant change, check WHY articulation |
| 3 | ADR alignment | Cross-reference against docs/adr/ decisions |
| 4 | Score & report | Understanding Score (0-5) with specific gaps |
**Scope:** Runs in all 9 code-producing workflows: feature, refactor, bugfix, migration, batch-operation, deployment, performance, quality-audit, verification.
## Workflow
### Step 1: Gather Changes
```bash
git diff --stat main...HEAD
```
List all changed files since branch diverged from main. Filter to significant changes (skip formatting, imports-only). If on main or no branch history, use `git diff --stat HEAD~5` as fallback.
### Step 2: Reasoning Audit
For each significant change, evaluate:
- **WHY articulated?** Was there a Design Intent statement or commit message explaining reasoning?
- **Alternatives considered?** Did the change mention rejected approaches?
- **Principle identified?** Can the change be linked to a known pattern/ADR?
### Step 3: ADR Alignment
Cross-reference against `docs/adr/`:
- Does this change align with or deviate from existing ADRs?
- If deviating, is the deviation documented and justified?
### Step 4: Understanding Score
**Scoring Rubric:**
| Score | Criteria |
|-------|----------|
| 5 | All changes have articulated WHY, alternatives considered, ADR alignment verified |
| 4 | Most changes explained, minor gaps in reasoning |
| 3 | Some reasoning, some "followed the pattern" without explanation |
| 2 | Mostly compliance-based, little reasoning articulated |
| 1 | No reasoning articulated -- pure pattern following |
| 0 | Changes contradict existing ADRs without justification |
**Output format:**
```
## Understanding Score: [X]/5
### Reasoning Found
- [file]: [reasoning articulated]
### Reasoning Gaps
- [file]: [what's missing -- e.g., "no justification for choosing CQRS over simple CRUD"]
### ADR Alignment
- [ADR-001]: Aligned / Deviated (justified) / Deviated (unjustified)
### Recommendation
[If score < 3: "Investigate whether changes were mechanical. Consider documenting the WHY before committing."]
```
## Important Notes
- This is a soft review -- never blocks commits
- Treat score < 3 as a flag to investigate, not a failure
- Focus on architectural decisions, not formatting choices
- When in doubt, ask: "Could someone explain why this change was made without reading the diff?"
## IMPORTANT Task Planning Notes
- Always plan and break many small todo tasks
- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed
This skill audits completed features or refactors to verify reasoning quality and produces an Understanding Score (0-5). It flags gaps in documented intent, checks alignment with architecture decision records (ADRs), and gives concrete recommendations for follow-up. Use it as a lightweight, non-blocking quality gate focused on why changes were made.
The skill gathers changed files from the current branch and filters to significant edits. For each change it inspects commit messages, design intent notes, and code comments to see whether the WHY, alternatives, and applied principles are articulated. It cross-references docs/adr/ for alignment, then computes an Understanding Score and emits a report listing reasoning found, gaps, ADR alignment status, and recommendations.
Is this review blocking merges?
No. This is a soft review to surface understanding gaps. Scores below the threshold are flags for discussion and follow-up tasks, not blockers.
What if no ADRs exist?
If no ADRs are present, the skill checks for local rationale and recommends creating an ADR for decisions that affect architecture or long-term behavior.