@hopla/claude-setup 1.6.0 → 1.8.0

package/files/commands/guides/review-checklist.md

@@ -0,0 +1,75 @@
+# Guide: Creating a Project-Specific Review Checklist
+
+Use this guide to create a `.agents/guides/review-checklist.md` file in your project with code review checks specific to your tech stack, domain, and known anti-patterns. The `/hopla-code-review` command loads this file automatically when it exists, applying your custom checks alongside the standard review categories.
+
+---
+
+## When to Create This
+
+Create a review checklist when:
+- The same bug pattern appears in **2+ code reviews** (e.g., stale closures in grid callbacks)
+- Your project uses a framework with non-obvious gotchas (AG Grid, Hono, Prisma, D3, etc.)
+- A `/hopla-system-review` flags a recurring issue that should be caught during code review
+- A `/hopla-execution-report` documents a new technical pattern in its "Technical Patterns Discovered" section
+
+---
+
+## File Location
+
+```
+your-project/
+└── .agents/
+    └── guides/
+        └── review-checklist.md    ← Create this file
+```
+
+---
+
+## Template
+
+Use this structure for your project's review checklist:
+
+```markdown
+# Project Review Checklist
+
+## Framework-Specific Checks
+
+### [Framework Name, e.g., AG Grid]
+- [ ] Cell editors and callbacks use `useRef` for state, not inline closures (prevents stale closure bugs)
+- [ ] New grid instances include `data-ag-theme-mode` attribute
+- [ ] Custom renderers set `cellDataType: false` to prevent auto-detection overrides
+- [ ] `refreshCells` is called for computed columns when dependencies change
+
+### [Framework Name, e.g., Hono]
+- [ ] Static routes (`/users/all`) are defined BEFORE parameterized routes (`/users/:id`)
+- [ ] All endpoints have input validation (required fields, format, limits)
+- [ ] DELETE routes are ordered correctly (specific before generic)
+
+## Domain-Specific Checks
+
+- [ ] [Check description — patterns unique to your business domain]
+- [ ] [Check description]
+
+## Known Anti-Patterns
+
+Patterns that have caused bugs in this project before:
+
+| Anti-Pattern | What to Look For | Correct Pattern |
+|---|---|---|
+| Stale closure in grid callback | Inline function passed to `onCellValueChanged` | Use `useRef` + stable callback via `useCallback` |
+| Route shadowing | Static route after `/:id` route | Define static routes first |
+| Missing IMEI validation | IMEI field accepts any string | Validate exactly 15 digits |
+| Side effect in JSX render | `array.push()` inside `.map()` | Compute before return, use `useMemo` |
+```
+
+---
+
+## Maintenance
+
+Update this file when:
+- `/hopla-system-review` flags a recurring bug pattern (3+ occurrences across reviews)
+- `/hopla-execution-report` discovers a new technical pattern in "Technical Patterns Discovered"
+- A code review finds a bug that should have been caught by a checklist item
+- A framework is upgraded and known gotchas change
+
+Keep the checklist focused — remove items once they become second nature to the team or are enforced by linting rules.

package/files/commands/hopla-code-review.md

@@ -13,6 +13,8 @@ Read `CLAUDE.md` or `AGENTS.md` to understand project standards and patterns.
 
 If `.agents/guides/` exists, read any guides relevant to the files being reviewed (e.g. `@.agents/guides/api-guide.md` when reviewing API changes). These guides define the expected patterns for specific task types.
 
+If `.agents/guides/review-checklist.md` exists, read it and apply the project-specific checks it defines in addition to the standard checks below. Project-specific checklists cover framework gotchas and domain anti-patterns unique to the project (e.g., AG Grid stale closures, Hono route ordering).
+
 ## Step 2: Identify Changed Files
 
 ```bash
@@ -31,11 +33,15 @@ For each changed file, look for:
 - Off-by-one errors, incorrect conditionals
 - Missing error handling, unhandled edge cases
 - Race conditions or async issues
+- Stale closures — callbacks passed to imperative APIs (grids, charts, maps) that capture stale state instead of using refs or stable references
+- Unhandled promise rejections — `.then()` without `.catch()`, async calls without `try/catch` in non-void contexts
+- Side effects inside JSX render — mutations of arrays/objects inside `.map()` in JSX (breaks React strict mode, causes double-execution bugs)
 
 **2. Security Issues**
 - Exposed secrets or API keys
 - SQL/command injection vulnerabilities
-- Insecure data handling or missing input validation
+- Missing input validation on API endpoints — required fields, format constraints (regex, length), payload size limits
+- Insecure data handling — raw user input in queries, responses exposing internal data or stack traces
 - XSS vulnerabilities (frontend)
 
 **3. Performance Problems**
@@ -44,7 +50,7 @@ For each changed file, look for:
 - Memory leaks
 
 **4. Code Quality**
-- DRY violations
+- DRY violations — before flagging, search for similar functions/constants elsewhere in the codebase; suggest extraction to a shared module if the same logic exists in multiple places
 - Poor naming or overly complex functions
 - Missing TypeScript types or `any` usage
 
@@ -52,6 +58,10 @@ For each changed file, look for:
 - Follows project conventions from CLAUDE.md
 - Consistent with existing codebase style
 
+**6. Route & Middleware Ordering**
+- Static routes defined AFTER parameterized routes (e.g., `/users/all` after `/users/:id`) causing shadowing — the parameterized route captures requests meant for the static one
+- Middleware applied in incorrect order (e.g., auth after route handler, CORS after response sent)
+
 ## Step 4: Verify Issues Are Real
 
 Before reporting, confirm each issue is legitimate:

package/files/commands/hopla-execute.md

@@ -87,17 +87,21 @@ Work through each task in the plan sequentially. For each task:
 
 1. **Announce** the task you are starting (e.g., "Starting Task 2: Create the filter component")
 2. **Follow the pattern** referenced in the plan — do not invent new patterns
-3. **Implement** only what the task specifies — nothing more
-4. **Validate** the task using the method specified in the plan's validate field
-5. **Report completion** with a brief status: what was done, what was skipped, any decision made
-6. **Do not proceed** to the next task if the current one fails validation
+3. **Check for existing implementations** — before creating new functions, constants, or utility modules, search the codebase for existing implementations that serve the same purpose. Reuse or extend rather than duplicate. DRY violations were the #1 code quality issue across 28 implementations.
+4. **Implement** only what the task specifies — nothing more
+5. **Validate** the task using the method specified in the plan's validate field
+6. **Report completion** with a brief status: what was done, what was skipped, any decision made
+7. **Do not proceed** to the next task if the current one fails validation
 
-**Git strategy:** Do not commit after individual tasks. Keep all changes staged but uncommitted until the full plan passes validation (Step 5). This allows a clean revert if later tasks fail.
+**Git strategy:**
+- **Plans with 1–7 tasks:** Do not commit after individual tasks. Keep all changes staged but uncommitted until the full plan passes validation (Step 5). This allows a clean revert if later tasks fail.
+- **Plans with 8+ tasks (or plans with `## Phase Boundaries`):** Commit at each phase boundary defined in the plan. Run Level 1–2 validation (lint + types) before each intermediate commit. Use commit message format: `feat(<scope>): <feature> — phase N of M`. This prevents losing work on large implementations if later phases fail.
 
 **Pause and report if, during implementation:**
 - A task is ambiguous or has multiple valid implementations
 - Something unexpected is discovered that could affect subsequent tasks
 - The plan's structure or ordering doesn't match conventions used elsewhere in the project
+- A new API route might shadow or be shadowed by an existing parameterized route (check route ordering — e.g., `/users/all` must be defined before `/users/:id`)
 
 Do not improvise silently. When in doubt, stop and ask.
 
@@ -107,7 +111,7 @@ If the user requests changes that are NOT in the plan during execution:
 
 1. **Acknowledge** the request
 2. **Assess** whether it's a small adjustment (< 5 minutes, same files) or a new feature
-3. **If small adjustment:** implement it and flag it as a deviation in the completion report
+3. **If small adjustment:** implement it and flag it as a deviation in the completion report. Even for small adjustments, validate with the same rigor as planned tasks — check for DRY violations, verify pattern adherence, and run the relevant validation level before moving on.
 4. **If new feature or significant addition:**
    - Suggest committing the current planned work first
    - Then create a new branch or add it to the backlog

package/files/commands/hopla-execution-report.md

@@ -14,6 +14,14 @@ git diff HEAD
 git ls-files --others --exclude-standard
 ```
 
+Also check for recent code reviews:
+
+```bash
+ls -t .agents/code-reviews/ 2>/dev/null | head -5
+```
+
+If a code review exists for this feature, note its path for the Code Review Findings section below.
+
 ## Step 2: Generate Report
 
 Save to: `.agents/execution-reports/[feature-name].md`
@@ -36,6 +44,13 @@ Use the following structure:
 - Unit Tests: ✓/✗ [X passed, Y failed]
 - Integration Tests: ✓/✗ [X passed, Y failed]
 
+### Code Review Findings
+
+- **Code review file:** [path to `.agents/code-reviews/[name].md`, or "Not run"]
+- **Issues found:** [count by severity: X critical, Y high, Z medium, W low]
+- **Issues fixed before this report:** [count]
+- **Key findings:** [1-2 sentence summary of the most significant issues found]
+
 ### What Went Well
 
 List specific things that worked smoothly:
@@ -46,6 +61,16 @@ List specific things that worked smoothly:
 List specific difficulties encountered:
 - [what was difficult and why]
 
+### Bugs Encountered
+
+Categorize each bug found during implementation:
+
+| Bug | Category | Found By | Severity |
+|-----|----------|----------|----------|
+| [description] | stale closure / validation / race condition / styling / scope mismatch / type error / route ordering / other | lint / types / tests / code review / manual testing | critical / high / medium / low |
+
+If no bugs were encountered, write "No bugs encountered during implementation."
+
 ### Divergences from Plan
 
 For each divergence from the original plan:
@@ -56,11 +81,28 @@ For each divergence from the original plan:
 - **Reason:** [why this divergence occurred]
 - **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
 
+### Scope Assessment
+
+- **Planned tasks:** [number of tasks in the original plan]
+- **Executed tasks:** [number of tasks actually completed]
+- **Unplanned additions:** [count and brief description of work not in the original plan]
+- **Scope accuracy:** On target | Under-scoped (took more work than planned) | Over-scoped (simpler than expected)
+
 ### Skipped Items
 
 List anything from the plan that was not implemented:
 - [what was skipped] — Reason: [why]
 
+### Technical Patterns Discovered
+
+New gotchas, patterns, or conventions learned during this implementation that should be documented:
+
+- **Pattern/Gotcha:** [description]
+- **Where it applies:** [what type of feature or context triggers this]
+- **Suggested documentation:** [which file should capture this: CLAUDE.md, `.agents/guides/review-checklist.md`, or a new guide]
+
+If nothing new was discovered, write "No new patterns discovered."
+
 ### Recommendations
 
 Based on this implementation, what should change for next time?

package/files/commands/hopla-git-commit.md

@@ -45,7 +45,18 @@ Present the proposed commit message to the user **before executing**:
 
 Wait for explicit approval before running `git commit`.
 
-## Step 5: Execute Commit
+## Step 5: Version Bump (if configured)
+
+Before committing, check the project's `CLAUDE.md` for a `## Versioning` section. If it exists:
+
+1. Read the versioning configuration (command, trigger, files)
+2. Check if the **trigger condition** matches (e.g., specific branches, always, etc.)
+3. If it matches, run the version bump command
+4. Stage the version files alongside the other changes
+
+If no `## Versioning` section exists in the project's `CLAUDE.md`, skip this step entirely.
+
+## Step 6: Execute Commit
 
 Once approved, create the commit:
 
@@ -53,7 +64,7 @@ Once approved, create the commit:
 git commit -m "<type>(<scope>): <description>"
 ```
 
-## Step 6: Push Reminder
+## Step 7: Push Reminder
 
 After committing, remind the user:
 

package/files/commands/hopla-git-pr.md

@@ -104,7 +104,7 @@ After showing the PR URL, suggest:
 
 After the user confirms the PR was approved and merged on GitHub, run the cleanup workflow based on the branch type:
 
-### For all branch types:
+### For feature and fix branches (merged to `dev`/`develop`):
 
 ```bash
 git checkout [base-branch]
@@ -113,7 +113,9 @@ git branch -d [merged-branch]
 git push origin --delete [merged-branch] 2>/dev/null  # skip if GitHub already deleted it
 ```
 
-### Additional steps for `hotfix/*` and `release/*`:
+**Important:** When `dev` is merged to `main` via PR, do NOT pull `main` back into `dev` — `dev` already has all the commits. Only sync `main` → `dev` for hotfix/release branches (see below).
+
+### Additional steps for `hotfix/*` and `release/*` ONLY:
 
 These branches were merged to `main` but `develop` also needs the changes:
 

package/files/commands/hopla-plan-feature.md

@@ -44,6 +44,7 @@ Investigate the areas of the codebase relevant to this feature:
 - Locate similar features already implemented to use as reference
 - Find the entry points that will need to be modified or extended
 - Identify potential conflicts or dependencies
+- **DRY check:** Before specifying new utility functions, constants, or helpers in the plan, search for existing implementations that can be reused or extended. DRY violations were the #1 code review finding across 28 implementations.
 
 Use the Grep tool to find relevant files (pattern: relevant keyword, case-insensitive).
 
@@ -66,6 +67,8 @@ Based on research, define:
 - **Derived/computed values:** If any value is calculated from other fields, specify the exact formula including how stored values are interpreted (sign, units, semantics), AND how derived values propagate when inputs change (event system, reactivity, polling, etc.)
 - **Interaction states & edge cases:** For features involving interactive UI (forms, grids, keyboard navigation, wizards, CLI interactions), define a matrix of user interactions and their expected behavior. Cover: all keyboard shortcuts (both directions — e.g., Tab AND Shift+Tab), state transitions (empty → editing → saved → error), and boundary conditions (first item, last item, empty list, maximum items). This prevents iterative fix rounds that consumed up to 40% of session time in past implementations.
 - **API input validation:** For every API endpoint being created or modified, specify: required fields, field format constraints (e.g., "IMEI must be exactly 15 digits"), payload size limits, and what the user sees on validation failure. This was the #2 most common gap in past plans — validation was only added after code review in 4 of 7 implementations.
+- **Bidirectional data interactions:** If feature A updates data that feature B displays, does B need to react? If adding an item triggers validation, does editing trigger re-validation? Map all data mutation → side effect chains, not just keyboard navigation. Missed bidirectional interactions were a recurring planning blind spot.
+- **AI/LLM prompt tasks:** If the plan involves creating or modifying AI prompts (system prompts, prompt templates, LLM-based features), add an explicit task for testing against real data with 2-3 iteration cycles budgeted. AI prompt engineering rarely works on the first attempt.
 - **User preferences check:** Before specifying UI architecture (modal vs. inline, page vs. panel, dialog vs. drawer), verify against MEMORY.md and conversation history for established preferences. In past implementations, plans that specified modals were rejected because the user preferred inline panels — this caused rework. When no preference exists, note it as a decision point for the user to confirm.
 
 ## Phase 5: Generate the Plan
@@ -88,6 +91,11 @@ Use this structure:
 ## Out of Scope
 - [Anything explicitly excluded]
 
+## Likely Follow-ups
+[Features or changes naturally adjacent to this work that the user may request during or after execution. Historical data: 71% of sessions had scope expansion. Listing these upfront helps the executing agent handle them via the Scope Guard rather than improvising.]
+- [Follow-up 1]
+- [Follow-up 2]
+
 ## Git Strategy
 - **Base branch:** `[develop | dev | main — specify which branch to create the feature branch from]`
 - **Feature branch:** `feature/[kebab-case-name]`
@@ -166,10 +174,22 @@ Scoring guide:
 
 ## Notes for Executing Agent
 [Any important context, warnings, or decisions made during planning that the executing agent needs to know]
+
+> **UI Styling Note:** UI styling specifications (colors, sizes, variants, labels, spacing) are `[provisional]` proposals. Historical data shows these change in 50%+ of implementations based on user feedback. Implement as specified but do not over-invest in pixel-perfect adherence — expect iteration.
 ```
 
 ---
 
+### Plan Size Check
+
+After generating the plan, count the implementation tasks (excluding test tasks):
+
+- **3–7 tasks:** Optimal size. Proceed as-is.
+- **8–11 tasks:** Consider grouping tasks into logical phases with intermediate commit points. Add a `## Phase Boundaries` section to the plan listing where commits should happen.
+- **12+ tasks:** The plan should be split into multiple plans or phased with mandatory intermediate commits. Historical data: plans with 12+ tasks scored 6/10 alignment vs 10/10 for 3–7 task plans. Add phase boundaries and consider whether independent task groups can be separate plans.
+
+---
+
 ## Phase 6: Verify the Plan
 
 Before saving the draft, review the plan against these criteria:
@@ -188,6 +208,8 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **Git strategy specified:** Base branch and feature branch are defined in `## Git Strategy`
 - [ ] **Interaction matrix included:** If the feature involves interactive UI, the `## Interaction Matrix` section is filled out — or explicitly marked as N/A with justification
 - [ ] **Time-box on risky tasks:** Any task involving unfamiliar libraries, heuristic parsing, or known-complex behavior (auto-sizing, animation, real-time sync) has a Time-box with a fallback strategy
+- [ ] **Plan size checked:** If >8 tasks, phase boundaries are defined with intermediate commit points. If >12 tasks, split justification is provided or phases are created.
+- [ ] **Likely follow-ups listed:** If the Out of Scope section has items, the Likely Follow-ups section is populated with naturally adjacent work the user may request
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/files/commands/hopla-system-review.md

@@ -30,8 +30,9 @@ If no matching review exists, continue with Step 1.
 
 ## Step 1: Load All Context
 
-Read these four artifacts in order:
+Read these artifacts in order:
 
+0. `.agents/system-reviews/` — Read ALL previous system review files (if any exist) to identify recurring patterns. Pay special attention to: bug categories that appear across multiple reviews, process improvement suggestions that were made before but not yet applied, and alignment score trends (improving or declining).
 1. `.claude/commands/plan-feature.md` — understand how plans are created
 2. **$1** (the plan) — what the agent was supposed to do
 3. `.claude/commands/execute.md` — understand how execution is guided
@@ -77,6 +78,23 @@ For each problematic divergence, identify the root cause:
 - Was a validation step missing?
 - Was a manual step repeated that should be automated?
 
+## Step 5.5: Cross-Review Pattern Detection
+
+If previous system reviews exist in `.agents/system-reviews/`, compare the current findings against them:
+
+### Recurring Bug Patterns
+For each bug category in this implementation, check if the same category appeared in previous reviews. If a pattern appears 3+ times:
+- Flag it as a **systemic issue** that needs a structural fix (not just a process note)
+- Suggest adding it to `.agents/guides/review-checklist.md` as a project-specific check
+- Example: "Stale closure bugs found in 3 of last 5 implementations → add to review checklist"
+
+### Unresolved Improvements
+Cross-reference improvement suggestions from previous reviews. If a suggestion was made before and NOT yet applied:
+- Check if the suggested CLAUDE.md update was made
+- Check if the suggested command update was made
+- Check if the suggested guide was created
+- List any improvements that were suggested 2+ reviews ago and are still pending
+
 ## Step 6: Generate Process Improvements
 
 Suggest specific actions based on patterns found:
@@ -142,6 +160,13 @@ root_cause: [unclear plan | missing context | missing validation | other]
 **What needs improvement:** [specific process gaps]
 **For next implementation:** [concrete changes to try]
 
+### Cross-Review Trends (if previous reviews exist)
+
+- **Recurring bug categories:** [list categories that appeared in 2+ reviews, with count — e.g., "stale closures: 3 occurrences"]
+- **Improvement backlog:** [list suggestions from previous reviews not yet applied]
+- **Alignment trend:** [list last 3–5 alignment scores with feature names, e.g., "parse-cache: 10, multi-org: 6, colors: 7"]
+- **Systemic issues:** [patterns appearing 3+ times that need structural fixes, not just process notes]
+
 ---
 
 ## Decision Framework — When to Update What

package/files/commands/hopla-validate.md

@@ -63,3 +63,8 @@ Provide a clear summary:
 If everything passes, confirm the project is healthy.
 
 If anything failed and could not be fixed, list the remaining issues and suggest next steps.
+
+## Next Step
+
+After validation passes, suggest:
+> "All validation levels passed. Consider running `/hopla-code-review` for a deeper analysis — code review catches bugs in 79% of implementations that pass automated validation (stale closures, missing input validation, route shadowing, unhandled promise rejections). Run `/hopla-code-review` to check, or `/hopla-git-commit` to commit directly."

package/files/skills/hopla-code-review/SKILL.md

@@ -13,6 +13,8 @@ Read `CLAUDE.md` or `AGENTS.md` to understand project standards and patterns.
 
 If `.agents/guides/` exists, read any guides relevant to the files being reviewed (e.g. `@.agents/guides/api-guide.md` when reviewing API changes). These guides define the expected patterns for specific task types.
 
+If `.agents/guides/review-checklist.md` exists, read it and apply the project-specific checks it defines in addition to the standard checks below. Project-specific checklists cover framework gotchas and domain anti-patterns unique to the project (e.g., AG Grid stale closures, Hono route ordering).
+
 ## Step 2: Identify Changed Files
 
 ```bash
@@ -31,11 +33,15 @@ For each changed file, look for:
 - Off-by-one errors, incorrect conditionals
 - Missing error handling, unhandled edge cases
 - Race conditions or async issues
+- Stale closures — callbacks passed to imperative APIs (grids, charts, maps) that capture stale state instead of using refs or stable references
+- Unhandled promise rejections — `.then()` without `.catch()`, async calls without `try/catch` in non-void contexts
+- Side effects inside JSX render — mutations of arrays/objects inside `.map()` in JSX (breaks React strict mode, causes double-execution bugs)
 
 **2. Security Issues**
 - Exposed secrets or API keys
 - SQL/command injection vulnerabilities
-- Insecure data handling or missing input validation
+- Missing input validation on API endpoints — required fields, format constraints (regex, length), payload size limits
+- Insecure data handling — raw user input in queries, responses exposing internal data or stack traces
 - XSS vulnerabilities (frontend)
 
 **3. Performance Problems**
@@ -44,7 +50,7 @@ For each changed file, look for:
 - Memory leaks
 
 **4. Code Quality**
-- DRY violations
+- DRY violations — before flagging, search for similar functions/constants elsewhere in the codebase; suggest extraction to a shared module if the same logic exists in multiple places
 - Poor naming or overly complex functions
 - Missing TypeScript types or `any` usage
 
@@ -52,6 +58,10 @@ For each changed file, look for:
 - Follows project conventions from CLAUDE.md
 - Consistent with existing codebase style
 
+**6. Route & Middleware Ordering**
+- Static routes defined AFTER parameterized routes (e.g., `/users/all` after `/users/:id`) causing shadowing — the parameterized route captures requests meant for the static one
+- Middleware applied in incorrect order (e.g., auth after route handler, CORS after response sent)
+
 ## Step 4: Verify Issues Are Real
 
 Before reporting, confirm each issue is legitimate:

package/files/skills/hopla-execution-report/SKILL.md

@@ -15,6 +15,14 @@ git diff HEAD
 git ls-files --others --exclude-standard
 ```
 
+Also check for recent code reviews:
+
+```bash
+ls -t .agents/code-reviews/ 2>/dev/null | head -5
+```
+
+If a code review exists for this feature, note its path for the Code Review Findings section below.
+
 ## Step 2: Generate Report
 
 Save to: `.agents/execution-reports/[feature-name].md`
@@ -37,6 +45,13 @@ Use the following structure:
 - Unit Tests: ✓/✗ [X passed, Y failed]
 - Integration Tests: ✓/✗ [X passed, Y failed]
 
+### Code Review Findings
+
+- **Code review file:** [path to `.agents/code-reviews/[name].md`, or "Not run"]
+- **Issues found:** [count by severity: X critical, Y high, Z medium, W low]
+- **Issues fixed before this report:** [count]
+- **Key findings:** [1-2 sentence summary of the most significant issues found]
+
 ### What Went Well
 
 List specific things that worked smoothly:
@@ -47,6 +62,16 @@ List specific things that worked smoothly:
 List specific difficulties encountered:
 - [what was difficult and why]
 
+### Bugs Encountered
+
+Categorize each bug found during implementation:
+
+| Bug | Category | Found By | Severity |
+|-----|----------|----------|----------|
+| [description] | stale closure / validation / race condition / styling / scope mismatch / type error / route ordering / other | lint / types / tests / code review / manual testing | critical / high / medium / low |
+
+If no bugs were encountered, write "No bugs encountered during implementation."
+
 ### Divergences from Plan
 
 For each divergence from the original plan:
@@ -57,11 +82,28 @@ For each divergence from the original plan:
 - **Reason:** [why this divergence occurred]
 - **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
 
+### Scope Assessment
+
+- **Planned tasks:** [number of tasks in the original plan]
+- **Executed tasks:** [number of tasks actually completed]
+- **Unplanned additions:** [count and brief description of work not in the original plan]
+- **Scope accuracy:** On target | Under-scoped (took more work than planned) | Over-scoped (simpler than expected)
+
 ### Skipped Items
 
 List anything from the plan that was not implemented:
 - [what was skipped] — Reason: [why]
 
+### Technical Patterns Discovered
+
+New gotchas, patterns, or conventions learned during this implementation that should be documented:
+
+- **Pattern/Gotcha:** [description]
+- **Where it applies:** [what type of feature or context triggers this]
+- **Suggested documentation:** [which file should capture this: CLAUDE.md, `.agents/guides/review-checklist.md`, or a new guide]
+
+If nothing new was discovered, write "No new patterns discovered."
+
 ### Recommendations
 
 Based on this implementation, what should change for next time?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {