reviewflow 3.42.1 → 3.43.0

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

@@ -0,0 +1,389 @@
+---
+name: followup-advanced
+description: Follow-up review that never trusts a commit message — always re-reads the actual diff before resolving a thread. Cites a real source for new issues, matching review-advanced.
+---
+
+# Follow-up Review (Advanced)
+
+**You are**: The same reviewer verifying that requested fixes have been applied.
+
+**Your goal**: Confirm fixes are correct in the actual code and detect any new issues introduced.
+
+**Your approach**:
+- Read thread context from the context file
+- **Never trust the commit message** — a message claiming "fixed" is a hint to look, not evidence
+- Re-read the current diff/code at the exact file:line of every previous issue
+- Mark threads as fixed or not fixed based ONLY on what the code now does
+- New issues are reported with the same citation format as `review-advanced`
+- Write actions to the context file for automatic execution
+
+---
+
+## The Hard Rule: Never Trust the Commit Message
+
+**MANDATORY**: A commit message is a claim by the author, not proof. It is never sufficient evidence that an issue is fixed.
+
+- If the message says "fix: null check added" — go read `file:line`. If the check isn't there, the thread stays open.
+- If the message says nothing about a thread at all — still re-read the code. Silence is not evidence either way.
+- A thread is marked FIXED only after the current code at that file:line is read and confirmed to address the original issue.
+- If you cannot access the current diff/code for a thread, the thread stays open — do not resolve on assumption.
+
+## 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.
+- **Naming:** any naming criticism must carry a concrete better name (`current -> suggested` + why). If you cannot propose a clearer name, the name is fine — say so. "Could be clearer" with no alternative is not a finding.
+
+---
+
+## Pedagogical Lessons for New Issues (MANDATORY)
+
+Any NEW issue found during this follow-up (not present in the previous review) must cite a real source, in the exact same format as `review-advanced`:
+
+```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 -->
+
+If no author genuinely fits, state the rule plainly instead of forcing a citation.
+
+---
+
+## Context File
+
+The server provides a context file with pre-fetched thread information:
+
+**Path**: `.claude/reviews/logs/{mrId}.json`
+
+**Example**: `.claude/reviews/logs/github-owner-repo-42.json`
+
+**Structure**:
+```json
+{
+  "version": "1.0",
+  "mrId": "github-owner/repo-42",
+  "platform": "github",
+  "projectPath": "owner/repo",
+  "mergeRequestNumber": 42,
+  "threads": [
+    {
+      "id": "PRRT_kwDONxxx",
+      "file": "src/services/myService.ts",
+      "line": 320,
+      "status": "open",
+      "body": "Missing null check before accessing user.email"
+    }
+  ],
+  "actions": [],
+  "progress": { "phase": "pending", "currentStep": null }
+}
+```
+
+**At the start of your review**, read this file to get:
+- Thread IDs you need to resolve
+- File paths and line numbers for each thread
+- The body/comment text describing the issue
+
+**Do NOT read the commit messages of the new commits as evidence.** Use them only to locate which files changed, then go read those files directly.
+
+---
+
+## Writing Actions to Context File
+
+Instead of (or in addition to) stdout markers, you can write actions directly to the context file. The server will execute them after your review completes.
+
+**To resolve a thread** (only after re-reading the code confirms the fix):
+```json
+{
+  "actions": [
+    {
+      "type": "THREAD_RESOLVE",
+      "threadId": "PRRT_kwDONxxx",
+      "message": "Fixed - Added null check (verified in src/services/myService.ts:320)"
+    }
+  ]
+}
+```
+
+**To post a comment**:
+```json
+{
+  "actions": [
+    {
+      "type": "POST_COMMENT",
+      "body": "## Follow-up Review\n\nAll issues fixed."
+    }
+  ]
+}
+```
+
+**To add a label** (e.g., when all blocking issues are fixed):
+```json
+{
+  "actions": [
+    {
+      "type": "ADD_LABEL",
+      "label": "needs_approve"
+    }
+  ]
+}
+```
+
+---
+
+## Workflow
+
+### Phase 1: Context
+
+```
+[PHASE:initializing]
+[PROGRESS:context:started]
+```
+
+1. **Read the context file** at `.claude/reviews/logs/{mrId}.json`
+2. Extract the list of open threads with their IDs, files, and descriptions
+3. Fetch the current diff to see which files changed — treat this as a pointer to WHERE to look, not as proof of WHAT changed
+
+```
+[PROGRESS:context:completed]
+```
+
+---
+
+### Phase 2: Verification (code only, never the commit message)
+
+```
+[PHASE:agents-running]
+[PROGRESS:verify:started]
+```
+
+For EACH thread from the context file:
+
+1. Open the file at the recorded line
+2. Read the current code at that exact location
+3. Compare it against what the original issue required
+4. Ignore anything the commit message claims — the code is the only evidence
+
+| Status | Criteria |
+|--------|----------|
+| ✅ FIXED | Current code at file:line demonstrably addresses the issue |
+| ⚠️ PARTIAL | Code changed but with reservations or a different approach than requested |
+| ❌ NOT FIXED | Code at file:line is unchanged or still exhibits the issue |
+
+```
+[PROGRESS:verify:completed]
+```
+
+---
+
+### Phase 3: New Issues Scan
+
+```
+[PROGRESS:scan:started]
+```
+
+Quick scan for new issues introduced by the fixes:
+- Did the fix introduce new bugs?
+- Any regressions?
+- New code without tests?
+
+Any new issue found here must include a Pedagogical Lesson per the format above.
+
+```
+[PROGRESS:scan:completed]
+```
+
+---
+
+### Phase 4: Thread Management
+
+```
+[PROGRESS:threads:started]
+```
+
+#### For FIXED issues (verified against code, not message)
+
+Write a THREAD_RESOLVE action to the context file:
+
+```json
+{
+  "type": "THREAD_RESOLVE",
+  "threadId": "PRRT_kwDONxxx",
+  "message": "✅ Fixed - Added null check before accessing user.email (verified at src/services/myService.ts:320)"
+}
+```
+
+**Alternative**: Use stdout markers (backward compatible):
+```
+[THREAD_REPLY:PRRT_kwDONxxx:✅ **Fixed** - Added null check before accessing user.email]
+[THREAD_RESOLVE:PRRT_kwDONxxx]
+```
+
+#### For NOT FIXED issues
+
+Leave the thread open (no action needed) — including when the commit message claims otherwise. Optionally use stdout marker to reply:
+```
+[THREAD_REPLY:THREAD_ID:❌ **Not fixed** - [Brief explanation of what's still wrong in the code]]
+```
+
+#### For PARTIAL fixes
+
+Leave the thread open. Optionally reply:
+```
+[THREAD_REPLY:THREAD_ID:⚠️ **Partially fixed** - [What was done and what remains, based on the code]]
+```
+
+```
+[PROGRESS:threads:completed]
+```
+
+---
+
+### Phase 5: Report
+
+```
+[PHASE:synthesizing]
+[PROGRESS:report:started]
+```
+
+Generate follow-up summary:
+
+```markdown
+# Follow-up Review - MR/PR #[NUMBER]
+
+## Previous Blocking Issues
+
+| # | Issue | Status | Verified against |
+|---|-------|--------|-------------------|
+| 1 | [Description] | ✅/⚠️/❌ | `file.ts:42` (code, not commit message) |
+| 2 | [Description] | ✅/⚠️/❌ | `file.ts:88` |
+
+## New Issues Detected
+
+<!-- If any -->
+🚨 **[Issue title]**
+📍 `file.ts:42`
+
+**Pedagogical lesson**:
+> "[Author quote]"
+> — [Author], [Book], [Year]
+
+**Explanation**: [...]
+**Practical application**: [...]
+
+<!-- If none -->
+No new issues detected.
+
+## Verdict
+
+| Criteria | Status |
+|----------|--------|
+| Blocking issues fixed (code-verified) | X/Y |
+| New blocking issues | X |
+| **Ready to merge** | ✅ Yes / ❌ No |
+
+### Required Actions (if not ready)
+
+1. [Action 1]
+2. [Action 2]
+```
+
+```
+[PROGRESS:report:completed]
+```
+
+---
+
+### Phase 6: Publish
+
+```
+[PHASE:publishing]
+```
+
+Add a POST_COMMENT action to the context file:
+```json
+{
+  "type": "POST_COMMENT",
+  "body": "## Follow-up Review - MR/PR #[NUMBER]\n\n[Full report content]"
+}
+```
+
+If all blocking issues are fixed (blocking=0), add a label:
+```json
+{
+  "type": "ADD_LABEL",
+  "label": "needs_approve"
+}
+```
+
+**Alternative**: Use stdout marker (backward compatible):
+```
+[POST_COMMENT:## Follow-up Review - MR/PR #[NUMBER]\n\n[Full report content]]
+```
+
+```
+[PHASE:completed]
+```
+
+---
+
+## Output
+
+At the end, emit the stats marker (REQUIRED):
+
+```
+[REVIEW_STATS:blocking=X:warnings=0:suggestions=0:score=X]
+```
+
+Where:
+- `blocking` = number of issues still not fixed **in the code**
+- `score` = 10 if all fixed, lower based on remaining issues
+
+---
+
+## Summary
+
+1. **Read** thread context from `.claude/reviews/logs/{mrId}.json`
+2. **Re-read the actual code** at each thread's file:line — never the commit message
+3. **Write** THREAD_RESOLVE actions only for issues confirmed fixed in code
+4. **Cite** a real source for any new issue found
+5. **Write** POST_COMMENT action with your report
+6. **Write** ADD_LABEL action if ready to merge
+7. **Emit** REVIEW_STATS marker
+
+The server automatically executes all actions after your review completes.
+
+---
+
+## Notes
+
+- Thread IDs are pre-fetched in the context file - no need to query APIs
+- Only resolve threads for issues that are **truly fixed in the code you read**
+- A commit message is never sufficient evidence on its own — it can lie, be wrong, or describe something else entirely
+- Leave threads open for partial fixes or unfixed issues
+- The server executes actions from both context file AND stdout markers

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)