why-review
1
总安装量
1
周安装量
#50062
全站排名
安装命令
npx skills add https://github.com/duc01226/easyplatform --skill why-review
Agent 安装分布
antigravity
1
gemini-cli
1
Skill 文档
/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
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