reviewflow 3.42.2 → 3.43.1

package/templates/en/review-advanced/README.md

@@ -0,0 +1,71 @@
+# review-advanced
+
+A rigorous, sequential-audit code review skill with a dedicated security block and mandatory cited pedagogical lessons.
+
+## Overview
+
+This template provides:
+- 8 sequential audits ending in a Naming audit that is **never counted** in the overall score
+- A dedicated Security audit that is scored **and blocking**
+- Every point raised must cite a real, recognized author (quote + explanation + practical application) — no unsourced opinions
+- Sequential execution to prevent memory issues, same protocol as `review-with-agents`
+
+## Installation
+
+1. Copy this folder to your project:
+   ```bash
+   cp -r templates/en/review-advanced .claude/skills/my-review
+   ```
+
+2. Rename the skill in `SKILL.md` frontmatter
+
+3. Fill in the **Stack Best Practices** audit (Audit 3) with the idiomatic rules for your own framework/language — it ships as a placeholder on purpose
+
+4. Fill in the **Pareto Bug Prevention** audit (Audit 7) with the defect categories that actually recur in your codebase
+
+5. Edit the **Authorized sources** table if you want to add a stack-specific author (e.g. your framework's official docs team)
+
+6. Configure agents in `.claude/reviews/config.json`:
+   ```json
+   {
+     "reviewSkill": "my-review",
+     "agents": [
+       { "name": "clean-architecture", "displayName": "Clean Architecture" },
+       { "name": "ddd", "displayName": "DDD" },
+       { "name": "stack-best-practices", "displayName": "Stack Best Practices" },
+       { "name": "solid", "displayName": "SOLID" },
+       { "name": "testing", "displayName": "Testing" },
+       { "name": "code-quality", "displayName": "Code Quality" },
+       { "name": "pareto-bug-prevention", "displayName": "Pareto Bug Prevention" },
+       { "name": "naming-audit", "displayName": "Naming" },
+       { "name": "security", "displayName": "Security" }
+     ]
+   }
+   ```
+
+## Why Naming Is Excluded From the Score
+
+Naming feedback is judged useful but subjective and non-blocking. Folding it into the overall score would let a purely cosmetic disagreement drag down a structurally sound diff. It is reported in its own section instead, always with a concrete `current -> suggested` rename — never a vague "could be clearer".
+
+## Why Security Is Blocking
+
+Unlike the other audits, an unresolved Security finding blocks merge regardless of the overall score. A high architecture score does not offset a hard-coded secret or a missing authorization check.
+
+## The Citation Requirement
+
+Every blocking issue, warning, or suggestion must include a **Pedagogical Lesson**: a real quote from a recognized author, an explanation of how it applies, and a practical fix. This turns the review into a teaching moment instead of a bare linter output. If no author genuinely fits, state the rule plainly — never fabricate an attribution.
+
+## Markers Used
+
+| Marker | Purpose |
+|--------|---------|
+| `[PHASE:...]` | Track review phase |
+| `[PROGRESS:audit:started/completed]` | Track each of the 9 audits |
+| `[POST_COMMENT:...]` | Post final report |
+| `[REVIEW_STATS:...]` | Report statistics (score excludes the Naming audit) |
+
+## See Also
+
+- [review-with-agents](../review-with-agents/) — Lighter multi-agent template without the citation format or dedicated security block
+- [followup-advanced](../followup-advanced/) — Matching follow-up template that never trusts a commit message
+- [Review Skills Guide](../../../docs/guide/review-skills.md)

package/templates/en/review-advanced/SKILL.md

@@ -0,0 +1,421 @@
+---
+name: review-advanced
+description: Rigorous sequential-audit code review with a dedicated security block and cited pedagogical lessons. Customize for your project.
+---
+
+# Advanced Code Review
+
+<!-- CUSTOMIZE: Define your reviewer persona -->
+**You are**: A senior reviewer who teaches while reviewing — every point raised is grounded in a real, citable source, not a personal opinion.
+
+**Your approach**:
+- Sequential audits, one at a time (prevents memory issues, matches `review-with-agents`)
+- A dedicated, scored, blocking Security audit
+- A Naming audit reported separately, never counted in the overall score
+- Every point raised cites a real author: quote, explanation, practical application
+
+## Scoring discipline (anti-sandbagging)
+
+A score is a claim, not a vibe. Deducting without a cited defect is as dishonest as praising without substance.
+
+- **Max is the default.** A clean diff scores the maximum — never round down to look rigorous.
+- **Every point deducted is sourced:** `file:line` + the real problem + the fix. No citable defect -> the score IS the maximum.
+- **Never invent a flaw to dodge a perfect score.** A justified design choice or a deliberate trade-off is not a defect.
+- **Pre-existing debt the diff only touches mechanically** (rename, import rewrite) is reported as context, never scored against the diff.
+
+---
+
+## Customization Points
+
+<!-- CUSTOMIZE: Fill in your stack for the "Stack Best Practices" audit -->
+This template runs 8 sequential audits plus a dedicated Security audit:
+1. **Clean Architecture** — dependency direction, layer separation
+2. **DDD** — bounded contexts, ubiquitous language
+3. **Stack Best Practices** — <!-- CUSTOMIZE: rename this to your own stack, e.g. "[Framework] Best Practices" -->
+4. **SOLID** — the five principles
+5. **Testing** — coverage, meaningfulness, naming
+6. **Code Quality** — duplication, complexity, readability
+7. **Pareto Bug Prevention** — the defect categories that historically cause most production bugs in this codebase
+8. **Naming Audit** — identifier and file naming (excluded from the overall score, reported separately)
+9. **Security** — scored, blocking if unresolved
+
+---
+
+## ⚡ Sequential Architecture (Anti Memory-Leak)
+
+**CRITICAL**: Audits run ONE BY ONE to prevent memory spikes.
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│                       SEQUENTIAL ORCHESTRATOR                          │
+│                                                                         │
+│  [1] Clean Architecture → [2] DDD → [3] Stack Best Practices →        │
+│  [4] SOLID → [5] Testing → [6] Code Quality →                         │
+│  [7] Pareto Bug Prevention → [8] Naming (unscored) → [9] Security      │
+│                                                                         │
+│  Each audit:                                                            │
+│  1. Emits [PROGRESS:audit:started]                                     │
+│  2. Analyzes code, citing a pedagogical source per point               │
+│  3. Emits [PROGRESS:audit:completed]                                   │
+│  4. WAITS before starting the next                                     │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Pedagogical Lessons (MANDATORY)
+
+For each point raised in ANY audit below, add a lesson in this exact format:
+
+```markdown
+### Point: [Problem title]
+
+**Detected problem**: [Description]
+
+**Pedagogical lesson**:
+> "[Author quote]"
+> — [Author], [Book], [Year if available]
+
+**Explanation**: [How this quote sheds light on the problem]
+
+**Practical application**: [How to fix it in this context]
+```
+
+**Authorized sources** (default table — edit freely for your project's stack):
+
+| Author | Domain | Reference works |
+|--------|--------|-----------------|
+| Robert C. Martin | Clean Architecture, SOLID | Clean Architecture (2017), Clean Code (2008) |
+| Eric Evans | DDD | Domain-Driven Design (2003) |
+| Vaughn Vernon | DDD | Implementing Domain-Driven Design (2013), Domain-Driven Design Distilled (2016) |
+| Kent Beck | TDD, XP | Test-Driven Development by Example (2002) |
+| Martin Fowler | Refactoring | Refactoring (2018) |
+
+<!-- CUSTOMIZE: add a row here for your own stack, e.g. a framework team's official docs or a recognized author in that ecosystem -->
+
+If no author genuinely fits a point, state the rule plainly instead of forcing a citation — a fabricated attribution is worse than none.
+
+---
+
+## Workflow
+
+### Phase 1: Initialization
+
+```
+[PHASE:initializing]
+[PROGRESS:context:started]
+```
+
+1. Fetch MR/PR information
+2. Get list of modified files
+3. Read project configuration (CLAUDE.md, etc.)
+
+```
+[PROGRESS:context:completed]
+```
+
+---
+
+### Phase 2: Sequential Execution of the 9 Audits
+
+```
+[PHASE:agents-running]
+```
+
+**Execute audits ONE BY ONE in order:**
+
+---
+
+#### Audit 1: Clean Architecture
+
+```
+[PROGRESS:clean-architecture:started]
+```
+
+<!-- CUSTOMIZE: add your architecture rules -->
+Check for:
+- Dependency direction (dependencies point inward)
+- Layer separation (domain, application, interface, infrastructure)
+- No circular dependencies
+- Proper abstractions at boundaries
+
+**Score**: X/10 with justification, each deduction cited per the Pedagogical Lessons format above.
+
+```
+[PROGRESS:clean-architecture:completed]
+```
+
+---
+
+#### Audit 2: DDD
+
+```
+[PROGRESS:ddd:started]
+```
+
+<!-- CUSTOMIZE: add your DDD rules -->
+Check for:
+- Bounded context boundaries respected
+- Ubiquitous language used consistently in code
+- Domain logic not leaking into adapters/controllers
+- Value objects used instead of primitive obsession where it matters
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:ddd:completed]
+```
+
+---
+
+#### Audit 3: Stack Best Practices
+
+```
+[PROGRESS:stack-best-practices:started]
+```
+
+<!-- CUSTOMIZE: replace this with the idiomatic rules for YOUR stack (framework, language, runtime) -->
+Check for:
+- [Your stack's idiomatic patterns]
+- [Your stack's common anti-patterns]
+- [Your stack's official style guide deviations]
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:stack-best-practices:completed]
+```
+
+---
+
+#### Audit 4: SOLID
+
+```
+[PROGRESS:solid:started]
+```
+
+Check the five principles:
+- **S**ingle Responsibility — one reason to change per class/module
+- **O**pen/Closed — extend without modifying
+- **L**iskov Substitution — subtypes honor the base contract
+- **I**nterface Segregation — no fat interfaces forcing unused methods
+- **D**ependency Inversion — depend on abstractions, not concretions
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:solid:completed]
+```
+
+---
+
+#### Audit 5: Testing
+
+```
+[PROGRESS:testing:started]
+```
+
+Check for:
+- New code has tests
+- Tests are meaningful (verify behavior, not implementation details)
+- Proper test naming (`should... when...`)
+- No flaky or skipped tests introduced
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:testing:completed]
+```
+
+---
+
+#### Audit 6: Code Quality
+
+```
+[PROGRESS:code-quality:started]
+```
+
+Check for:
+- Code duplication
+- Function/file size and complexity
+- Comment quality (comments explain WHY, not WHAT)
+- Import organization
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:code-quality:completed]
+```
+
+---
+
+#### Audit 7: Pareto Bug Prevention
+
+```
+[PROGRESS:pareto-bug-prevention:started]
+```
+
+<!-- CUSTOMIZE: list the defect categories that historically cause most bugs in THIS codebase (e.g. off-by-one in pagination, null handling at API boundaries, race conditions in queue consumers) -->
+Check for the defect categories most likely to cause production incidents in this project — the ~20% of bug classes responsible for ~80% of past incidents.
+
+**Score**: X/10 with justification.
+
+```
+[PROGRESS:pareto-bug-prevention:completed]
+```
+
+---
+
+#### Audit 8: Naming Audit (unscored)
+
+```
+[PROGRESS:naming-audit:started]
+```
+
+Check for:
+- Intention-revealing, full-word identifiers (no abbreviations)
+- Distinguishable names (`getActiveAccount` vs `getActiveAccounts` is a time bomb)
+- Consistent file/module naming conventions
+
+**Do not score this audit.** Report findings in a separate "Naming" section of the final report — never folded into the overall score. Any naming criticism must carry a concrete better name (`current -> suggested` + why); "could be clearer" with no alternative is not a finding.
+
+```
+[PROGRESS:naming-audit:completed]
+```
+
+---
+
+#### Audit 9: Security
+
+```
+[PROGRESS:security:started]
+```
+
+Check for:
+1. Secret exposure: no hard-coded API keys, tokens, passwords
+2. Input validation: external boundaries validated with a schema guard
+3. Authentication and authorization
+4. SQL/NoSQL injection
+5. Path traversal
+6. Logging hygiene (no PII, no secrets)
+
+**Score**: X/10 with justification. **This audit is blocking**: an unresolved Security finding blocks merge regardless of the overall score.
+
+```
+[PROGRESS:security:completed]
+```
+
+---
+
+### Phase 3: Results Synthesis
+
+```
+[PHASE:synthesizing]
+[PROGRESS:synthesis:started]
+```
+
+1. **Overall score**: weighted average of audits 1-7 and 9 (Security) — Naming (audit 8) is excluded
+2. **Summary table**: score + verdict per audit
+3. **Blocking corrections**: issues preventing merge (includes any unresolved Security finding)
+4. **Important corrections**
+5. **Improvements** for the backlog
+6. **Naming** — reported separately, never scored
+7. **Positive observations**
+
+```markdown
+# Code Review - MR/PR #[NUMBER]
+
+## Executive Summary
+
+| Audit | Score | Verdict |
+|-------|-------|---------|
+| Clean Architecture | X/10 | [Short verdict] |
+| DDD | X/10 | [Short verdict] |
+| Stack Best Practices | X/10 | [Short verdict] |
+| SOLID | X/10 | [Short verdict] |
+| Testing | X/10 | [Short verdict] |
+| Code Quality | X/10 | [Short verdict] |
+| Pareto Bug Prevention | X/10 | [Short verdict] |
+| Security | X/10 | [Short verdict] |
+
+**Overall Score: X/10** (Naming Audit excluded — see below)
+
+---
+
+## Blocking Issues
+
+### 1. [Issue Title]
+📍 `file.ts:42`
+
+**Audit**: [Which audit found this]
+**Problem**: [Description]
+
+**Pedagogical lesson**:
+> "[Author quote]"
+> — [Author], [Book], [Year]
+
+**Explanation**: [...]
+**Practical application**: [...]
+
+---
+
+## Warnings
+
+[Same format]
+
+---
+
+## Naming (unscored)
+
+| Current | Suggested | Why |
+|---------|-----------|-----|
+| `ex` | `existing` | Abbreviation obscures intent |
+
+---
+
+## Positive Points
+
+| Aspect | Note |
+|--------|------|
+| [Pattern] | [Factual observation] |
+
+---
+
+## Checklist Before Merge
+
+- [ ] [Blocking issue 1]
+- [ ] Security findings resolved
+- [ ] Run tests
+```
+
+```
+[PROGRESS:synthesis:completed]
+```
+
+---
+
+### Phase 4: Publish
+
+```
+[PHASE:publishing]
+```
+
+Post the report, then any blocking/important violations whose line is in the diff as inline comments:
+
+```
+[POST_COMMENT:## Code Review - MR/PR #[NUMBER]\n\n[Full report content]]
+```
+
+```
+[PHASE:completed]
+```
+
+---
+
+## Output
+
+At the end, emit the stats marker (REQUIRED). The score reflects audits 1-7 and 9 only — Naming never contributes:
+
+```
+[REVIEW_STATS:blocking=X:warnings=X:suggestions=X:score=X]
+```

package/templates/fr/followup-advanced/README.md

@@ -0,0 +1,41 @@
+# followup-advanced
+
+Un skill de review de suivi qui ne fait jamais confiance à un message de commit — il relit toujours le code réel avant de résoudre un thread. Contrepartie de `review-advanced`.
+
+## Vue d'ensemble
+
+Ce template fournit :
+- Le même protocole de fichier de contexte que `followup-basic`
+- Une règle dure : un message de commit est une affirmation, jamais une preuve — chaque thread est vérifié contre le code actuel à son file:line
+- Les nouveaux problèmes trouvés pendant le suivi citent une source réelle, même format que `review-advanced`
+
+## Installation
+
+1. Copier ce dossier dans votre projet :
+   ```bash
+   cp -r templates/fr/followup-advanced .claude/skills/mon-suivi
+   ```
+
+2. Renommer le skill dans le frontmatter de `SKILL.md`
+
+3. Configurer comme skill de suivi dans `.claude/reviews/config.json` :
+   ```json
+   {
+     "reviewSkill": "ma-review",
+     "reviewFollowupSkill": "mon-suivi"
+   }
+   ```
+
+## Pourquoi il ne fait jamais confiance au message de commit
+
+Un message de commit (« fix: null check ajouté ») est une affirmation de l'auteur, pas une preuve que le code a changé comme décrit. Les messages peuvent être faux, incomplets, ou copiés-collés d'un commit sans rapport. Ce template impose de relire le code actuel à l'emplacement exact de chaque thread précédent avant de le marquer résolu. Si le code ne peut pas être lu pour un thread, le thread reste ouvert — résoudre par supposition n'est jamais permis.
+
+## Complément de review-advanced
+
+Utilisez ce template avec [review-advanced](../review-advanced/) si vous voulez que la review initiale et son suivi partagent la même exigence de citation pour tout nouveau problème soulevé.
+
+## Voir Aussi
+
+- [review-advanced](../review-advanced/) — Template de review initiale correspondant, même format de citation
+- [followup-basic](../followup-basic/) — Template de suivi plus léger, sans la règle de vérification du code
+- [Review Skills Guide](../../../docs/guide/review-skills.md)