@martinffx/atelier 3.0.1 → 3.1.0

package/skills/code-review/references/rs.md

@@ -4,7 +4,9 @@
 
 Interactive interview mode to resolve code review findings. No subagents.
 
-The agent interviews the user one question at a time, multiple choice, until it has enough context to resolve all issues raised by the review.
+The agent interviews the user one question at a time, multiple choice, until each finding has
+a resolution. Fixes change the code. Intentional non-fix resolutions are recorded beside the
+relevant code so later reviews can honor the decision without restating the full finding.
 
 ## Prompt
 
@@ -17,9 +19,40 @@ Ask me questions 1 by 1, multiple choice.
 
 1. Load the review findings from the current conversation context
 2. Begin interviewing the user — one question at a time, always multiple choice
-3. Use answers to build understanding of how to resolve each finding
-4. Once all context is gathered, apply the fixes
-5. **Always ask user before applying fixes**
+3. Classify each finding as fix, intentional/accepted risk, false positive, or deferred
+4. Capture the rationale and reconsideration condition for every non-fix resolution
+5. Present one plan containing the exact fixes and proposed decision comments
+6. **Always ask the user before applying fixes or adding, changing, or removing comments**
+
+## Resolution Rules
+
+| Resolution | Action |
+|------------|--------|
+| Fix | Change the code; do not add a decision comment for a concern the change removes |
+| Intentional / accepted risk | Add or update a decision comment with the reason the behavior is intentional and when to reconsider it |
+| False positive | Add or update a decision comment that states the invariant or context that makes the concern inapplicable |
+| Deferred | Add a decision comment only when the user supplies a concrete reconsideration condition or tracking reference; otherwise leave the finding active |
+
+## Decision Comment Contract
+
+Use the language's native comment syntax and this tagged prose format:
+
+```text
+review-decision: <concern> — <rationale>. Reconsider if <condition>.
+```
+
+For example:
+
+```typescript
+// review-decision: retry count is intentionally unbounded — the caller enforces a deadline. Reconsider if this function becomes part of the public API.
+```
+
+- Put the comment at the closest stable code location that owns the relevant behavior or invariant.
+- Explain the code and its constraints, not the review conversation or the reviewer.
+- Keep the concern, rationale, and reconsideration condition specific enough to validate later.
+- Update an existing matching comment instead of adding a duplicate.
+- Remove or revise a comment when its concern is fixed or its assumptions no longer hold.
+- Do not create IDs, a registry entry, or duplicate comments across every affected call site.
 
 ## Guidelines
 
@@ -27,4 +60,7 @@ Ask me questions 1 by 1, multiple choice.
 - Always provide multiple choice answers (a, b, c, d...)
 - Start with the most ambiguous findings first
 - Skip findings that are clearly actionable without input
-- After all questions are answered, summarize the plan and confirm before making changes
+- For a non-fix choice, ask for the rationale or reconsideration condition only when the
+  conversation and repository do not already provide it
+- After all questions are answered, show exact proposed comments with the fix plan and confirm
+  before making changes

package/skills/code-subagents/SKILL.md

@@ -55,8 +55,9 @@ For shared-tree parallel work:
 
 1. Assign each task an exclusive file list before dispatch
 2. Do not let implementers stage or commit changes
-3. Capture a path-scoped `git diff` for each task when it reports completion
-4. Run tasks sequentially if their file ownership overlaps or cannot be isolated
+3. Capture full `git status`, including untracked files, before and after each task
+4. Capture the task's path-scoped patch and reject changes outside its assigned paths
+5. Run tasks sequentially if their file ownership overlaps or cannot be isolated
 
 ---
 
@@ -97,6 +98,7 @@ Give one fresh reviewer:
 - The complete requirements for work items in the batch
 - The relevant constraints
 - The path-scoped patch captured for each task
+- The full changed-file inventory, including untracked files
 - The implementers' reports and validation results
 
 The reviewer checks both requirements compliance and code quality:

package/skills/code-subagents/references/batch-reviewer-prompt.md

@@ -7,6 +7,11 @@ captured task patches, not a commit range.
 
 ```
 You are reviewing one completed implementation batch for requirements compliance and code quality.
+You are read-only: do not modify files, stage changes, or create commits.
+
+## Working Directory
+
+{WORKING_DIRECTORY}
 
 ## Batch Requirements
 
@@ -20,6 +25,10 @@ You are reviewing one completed implementation batch for requirements compliance
 
 {BATCH_PATCHES}
 
+## Complete Changed-File Inventory
+
+{CHANGED_FILES}
+
 ## Implementer Reports and Validation
 
 {IMPLEMENTER_REPORTS}

package/skills/code-subagents/references/implementor-prompt.md

@@ -17,6 +17,13 @@ You are implementing {WORK_ITEM_NAME}
 {Scene-setting: where this fits in the work, what was built before it, constraints, and
 existing patterns to follow}
 
+## File Ownership
+
+- **Owned files:** {OWNED_FILES}
+- **Forbidden files:** {FORBIDDEN_FILES}
+
+Do not modify files outside the owned list. Report immediately if the work requires one.
+
 ## Before You Begin
 
 If you have questions about:

package/skills/oracle-debug/SKILL.md

@@ -3,7 +3,7 @@ name: oracle-debug
 description: >
   Disciplined debugging methodology. Triggers on bug reports, test failures, "debug this",
   "diagnose this", unexpected behavior, build failures, integration issues, or performance
-  regressions. Always find root cause before attempting any fix.
+  regressions. Find root cause before a permanent corrective fix; contain urgent harm safely first.
 user-invocable: true
 ---
 
@@ -11,7 +11,8 @@ user-invocable: true
 
 Random fixes waste time and create new bugs. Quick patches mask underlying issues.
 
-**Core principle:** find root cause before attempting any fix. Symptom fixes are failure.
+**Core principle:** find root cause before a permanent corrective fix. Temporary containment is
+appropriate when needed to limit security, production, or data-loss impact.
 
 **Violating the letter of this process is violating the spirit of debugging.**
 
@@ -72,11 +73,13 @@ relevant modules before tracing.
 
    Iterate on the loop: make it faster, sharper, and more deterministic. A 30-second flaky loop is barely better than no loop.
 
-3. **Reproduce the bug.** Run the loop. Confirm the failure matches what the user described, is reproducible across runs, and the exact symptom is captured.
+3. **Reproduce the bug.** Run the loop when safe. Confirm the failure matches what the user
+   described and capture the exact symptom. When reproduction is unsafe or impossible, use
+   historical artifacts, static evidence, or targeted telemetry instead.
 4. **Check recent changes.** `git diff`, recent commits, new dependencies, config changes, environment differences.
 5. **Trace data flow.** In multi-component systems, add diagnostic instrumentation at each boundary:
-   - Log what data enters each component
-   - Log what data exits each component
+   - Record only the minimum fields needed at each component boundary
+   - Redact credentials, authorization data, session identifiers, personal data, and payloads
    - Verify environment/config propagation
    - Check state at each layer
 
@@ -85,7 +88,10 @@ relevant modules before tracing.
 
 ### Non-deterministic bugs
 
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelize, add stress, narrow timing windows, inject sleeps. A 50% flake is debuggable; 1% is not — keep raising the rate until it is.
+The goal is not a clean repro but a **higher reproduction rate**. Narrow timing windows and vary
+one condition at a time. Treat added delay or load as a perturbation, not proof. Do not replay
+state-changing traffic, stress production, or collect sensitive artifacts without explicit
+authorization and a safe operational plan.
 
 ### When you genuinely cannot build a loop
 
@@ -95,7 +101,8 @@ Stop and say so explicitly. Ask the user for:
 - A captured artifact (HAR, log dump, core dump, screen recording)
 - Permission to add temporary production instrumentation
 
-**Do not proceed to Phase 2 without a loop you believe in.**
+**Do not claim root cause without evidence you can explain.** A safe loop is preferred, but
+artifact-based investigation is valid when a loop is unavailable.
 
 ---
 
@@ -123,7 +130,8 @@ Use the scientific method.
 
    **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup becomes a single grep.
 
-4. **Performance regressions.** Logs are usually wrong. Establish a baseline measurement (timing harness, profiler, query plan), then bisect. Measure first, fix second.
+4. **Performance regressions.** Establish a baseline measurement using the least intrusive
+   evidence available, then bisect. Measure first, fix second.
 
 5. **When you don't know, say so.** Don't pretend. Ask for help or research more.
 
@@ -211,8 +219,7 @@ After each session, summarize:
 
 ## References
 
-- **Language-specific tools** → `references/language-tools.md`
 - **Common bug patterns** → `references/bug-patterns.md`
-- **Logging & techniques** → `references/techniques.md`
+- **Techniques and safety practices** → `references/techniques.md`
 
 Structure inspired by [obra/superpowers systematic-debugging](https://github.com/obra/superpowers).

package/skills/oracle-debug/references/techniques.md

@@ -1,157 +1,61 @@
 # Debugging Techniques
 
-## Print Debugging
+## Println Debugging
 
-### When to Use
-- Quick checks in development
-- When debugger isn't available
-- Understanding flow in unfamiliar code
-- Minimal reproducible cases
+Start with temporary, labeled output or the project's structured logger to establish execution
+order and inspect the values relevant to the current hypothesis. Print only the fields needed,
+include a unique session tag, and avoid tight loops. Move to tracing, profiling, or other heavier
+instrumentation only when focused logs cannot establish the evidence.
 
-### Best Practices
+Do not print credentials, authorization data, session identifiers, personal data, private
+payloads, or environment values. Remove temporary output once the investigation is complete.
 
-**Do:**
-- Print at function entry/exit to trace execution
-- Print variable values at key decision points
-- Use descriptive labels: `console.log('userId:', userId)`
-- Print full objects for inspection: `console.log(JSON.stringify(data, null, 2))`
+## Further Instrumentation
 
-**Don't:**
-- Leave print statements in production code
-- Print sensitive data (passwords, tokens)
-- Over-print (noise obscures signal)
-- Print in tight loops (use breakpoints instead)
+Instrument the smallest useful boundary. Record event order, identifiers, state transitions, and
+timing rather than entire payloads. Use a unique session tag for temporary instrumentation and
+remove only the instrumentation introduced for that session.
 
-### Tagged Debug Logs
+Never record credentials, authorization data, session identifiers, personal data, private
+payloads, or environment values. Treat captures, traces, and dumps as sensitive artifacts.
 
-When instrumenting during a debugging session, tag every temporary log with a
-unique prefix so cleanup is trivial:
+## Bisection
 
-```javascript
-console.log('[DEBUG-a4f2] userId:', userId);
-console.log('[DEBUG-a4f2] payload:', payload);
-```
+Narrow the failing path by disabling coherent branches, reducing inputs, or comparing a known-good
+revision with a known-bad revision. Keep the system valid while narrowing; arbitrary code removal
+can change the behavior being investigated.
 
-Cleanup: `grep -r '\[DEBUG-' .` → delete all matches.
+Before revision bisection, preserve unrelated work and record the starting revision. Reset to the
+starting state after the investigation.
 
-Untagged logs survive; tagged logs die.
+## Non-Deterministic Failures
 
----
+Record the conditions of every attempt: input, environment, timing, concurrency, seed, and result.
+Vary one condition at a time. Use delays and load only to perturb scheduling, never as proof of the
+cause. Prefer deterministic scheduling, fault injection, or recorded traces when available.
 
-## Structured Logging
+## Performance Investigation
 
-Better than `console.log` for production:
+Establish a representative baseline before changing code. Use measurements, profiling, tracing, or
+query plans that fit the suspected bottleneck. Avoid high-volume logging on the hot path because it
+can alter timing.
 
-```javascript
-const logger = {
-  debug: (msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, ...meta })),
-  info: (msg, meta) => console.info(JSON.stringify({ level: 'info', msg, ...meta })),
-  warn: (msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, ...meta })),
-  error: (msg, meta) => console.error(JSON.stringify({ level: 'error', msg, ...meta })),
-};
-```
+Some analysis tools execute the operation they inspect. Confirm whether a command is read-only and
+whether it can create load, acquire locks, or repeat side effects before using it outside an
+isolated environment.
 
-### Console Methods
+## Production Safety
 
-| Method | Use |
-|--------|-----|
-| console.log | General output |
-| console.debug | Debug info |
-| console.info | Informational |
-| console.warn | Warnings |
-| console.error | Errors |
-| console.table | Arrays/objects in table format |
-| console.trace | Stack trace |
-| console.time/timeEnd | Timing |
+Default to development, staging, or an isolated replica. Before production instrumentation,
+replay, or load generation, obtain explicit authorization and define scope, rate limits, rollback,
+and a stop condition. Replay only idempotent or dry-run operations unless the user explicitly
+accepts the side effects.
 
----
+## Cleanup
 
-## Binary Search Debugging
+Before closing the investigation:
 
-### Code Binary Search
-
-Comment out half the code to find where the bug is.
-
-### Git Bisect
-
-For regression bugs:
-
-```bash
-git bisect start
-git bisect bad
-git bisect good v1.2.3
-# Run your test, mark good/bad
-git bisect reset
-```
-
----
-
-## Rubber Ducking
-
-### The Process
-
-1. Describe the problem in detail
-2. Explain expected behavior
-3. Explain actual behavior
-4. Walk through the code line by line
-
----
-
-## Logging Strategies
-
-### What to Log
-
-| Log This | Don't Log This |
-|----------|----------------|
-| Request/response with IDs | Full request bodies |
-| Key decisions in code | Every loop iteration |
-| Error details with context | Stack traces |
-| Performance timing | Large data dumps |
-| User actions | Sensitive data (PII, passwords) |
-
-### Context to Include
-
-```javascript
-logger.error('Request failed', {
-  endpoint: '/api/users',
-  method: 'POST',
-  statusCode: 500,
-  userId: user?.id,
-  requestId: req.headers['x-request-id'],
-  duration: Date.now() - startTime,
-  errorMessage: error.message
-});
-```
-
-### Log Levels
-
-| Level | When |
-|-------|------|
-| DEBUG | Detailed debugging info |
-| INFO | Normal operation events |
-| WARN | Something unexpected, but handled |
-| ERROR | Operation failed |
-
----
-
-## Performance Regression Techniques
-
-### The Perf Branch
-
-For performance regressions, logs are usually wrong. Instead:
-
-1. **Establish a baseline measurement** using one of:
-   - Timing harness around the suspect code path
-   - `performance.now()` in browser / `process.hrtime()` in Node
-   - CPU profiler (Chrome DevTools, `node --prof`, py-spy, etc.)
-   - Database query planner (`EXPLAIN ANALYZE`)
-
-2. **Bisect** — narrow down which commit / change introduced the regression.
-
-3. **Measure first, fix second.** Do not optimise without data.
-
-### Hot Path Identification
-
-- Profile before guessing
-- Look for O(n²) algorithms, unnecessary renders, blocking operations
-- Check for N+1 queries, unbounded caches, recursive without memoisation
+- Remove temporary instrumentation and throwaway harnesses.
+- Preserve only sanitized evidence needed to explain the conclusion.
+- Re-run the original verification signal.
+- Record the confirmed cause, fix, and prevention measure.

package/skills/oracle-domain-modelling/SKILL.md

@@ -41,13 +41,16 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 │       └── docs/adr/
 ```
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+Read `docs/agents/domain.md` when it exists to locate the configured domain documents. Create files
+lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the
+first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
 
 ## During the session
 
 ### Challenge against the glossary
 
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately:
+When the user uses a term that conflicts with the existing language in the relevant `CONTEXT.md`,
+call it out immediately. Resolve `CONTEXT-MAP.md` first when present:
 
 > "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
 

package/skills/oracle-grill-me/SKILL.md

@@ -15,6 +15,9 @@ Ask the questions one at a time, waiting for feedback on each question before co
 
 If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
 
-Do not act on it until I confirm we have reached a shared understanding.
+Do not implement the proposed plan or decision until I confirm we have reached a shared
+understanding. Update domain documentation as terminology and decisions are resolved; when this
+session is nested in spec-brainstorm, return changed assumptions to that workflow for any required
+design update.
 
 Run this session using the `oracle-domain-modelling` skill.

package/skills/spec-brainstorm/SKILL.md

@@ -53,7 +53,8 @@ explain a unit's job in one sentence, it's doing too much.
 
 Explore the current structure first. Follow existing patterns. Targeted improvements only.
 No unrelated refactoring. Understand why things are the way they are before proposing
-changes.
+changes. Treat loaded skills as relevant guidance, not as a requirement to apply every pattern
+they contain.
 
 ### Decomposition
 
@@ -62,12 +63,18 @@ into sub-projects before diving into details. Each substantial sub-project gets
 and plan; bounded sub-projects can use Inline Plans. A spec that tries to cover three
 subsystems helps no one.
 
+Keep migrations separate from authorization, product behavior, infrastructure, schema, and
+test-platform projects. Do not use a migration as permission to redesign adjacent systems.
+
 ### YAGNI ruthlessly
 
 Remove unnecessary features from all designs. If a capability isn't needed for the first
 user story, it doesn't go in the spec. Every feature is a cost — to build, to test,
 to maintain, to understand later. Push back on scope creep during discovery.
 
+Future consumers do not justify shared infrastructure. A "reusable foundation" may describe
+an architectural quality, but it is not a user story or a current requirement.
+
 ---
 
 ## Step 1: Orient
@@ -154,7 +161,18 @@ Read the relevant codebase deeply. Not signatures — implementations, edge case
 handling, data flows. Trace callers and callees. Read tests to understand expected
 behaviour.
 
-Write findings directly into the spec as the foundation.
+Collect research findings for the spec as the foundation. Do not write `design.md` until the
+approved design sections are assembled in Step 4c.
+
+The research section must map each relevant concern to the code that already handles it and
+the current requirement that drives the decision:
+
+| Concern | Existing solution | Decision | Current requirement |
+|---------|-------------------|----------|---------------------|
+| IDs | Shared parser and ID type | reuse | Parse route parameters |
+
+Use only `reuse`, `modify`, `delete`, or `new` in the Decision column. Every `new` concept must
+map to a present requirement; a future or hypothetical consumer does not qualify.
 
 **Tell the human:** "I've written the research section of the spec. Ready for you to
 review before I continue with the design."
@@ -172,6 +190,9 @@ then write the spec file.
 
 Before settling on a design, present **2-3 approaches** with trade-offs.
 
+The first approach must keep the existing architecture and make the smallest correct change.
+Present broader approaches only when a current requirement makes their extra cost relevant.
+
 For each approach, address:
 
 1. **What it looks like** — Brief architecture sketch
@@ -181,6 +202,9 @@ For each approach, address:
 
 Lead with your recommended option and explain why it wins.
 
+Before asking the human to approve an approach or design batch, remove anything justified only
+by completeness, consistency, or hypothetical reuse.
+
 **Example:**
 
 > **Approach A: Single table with JSON columns**
@@ -323,6 +347,8 @@ After writing the file, check it with fresh eyes:
    decomposed in Step 2. If it's still too broad, flag it now.
 4. **Ambiguity check** — Could any requirement be interpreted two ways? If so,
    pick one interpretation, state it explicitly, and let the human correct you.
+5. **Necessity check** — Delete concepts justified only by completeness, consistency, or
+   hypothetical reuse. Confirm every remaining new concept maps to a current requirement.
 
 **Substance rule:** if a fix changes the substance of an approved section,
 re-present that section for approval. Wording and consistency fixes go inline —
@@ -334,14 +360,13 @@ note them at handoff.
 
 **Tell the human:**
 
-> "Spec written to `docs/specs/<path>`. Every section was approved during our
-> conversation - review it if you'd like, or we can go straight to the
-> Spec-backed Plan. Ready for spec-plan?"
+> "Spec written to `docs/specs/<path>`. Please confirm this assembled document before we move to
+> the Spec-backed Plan."
 
-If the human requests changes — in conversation or by annotating the file —
-address every note, update the spec, and re-run the self-review. If a change
-alters the substance of an approved section, re-present that section for
-approval before continuing.
+If the human requests changes — in conversation or by annotating the file — address every note,
+update the spec, and re-run the self-review. If a change alters the substance of an approved
+section, re-present that section for approval before continuing. Resolve questions that affect
+scope, architecture, contracts, data, security, or task ordering before handoff.
 
 The next step is **spec-plan** in Spec-backed mode. Do not start planning without the
 human's go-ahead. Do not write code.

package/skills/spec-finish/SKILL.md

@@ -10,20 +10,42 @@ user-invocable: true
 
 # Spec Finish
 
-Post-implementation workflow: validate → review → stack commits → prepare PR.
+Post-implementation workflow: simplify → synchronize docs → validate → review → prepare PR.
 
 ## Prerequisites
 
 Before starting, verify:
 1. All Spec-backed Plan tasks are complete
-2. Working directory is clean (committed or staged)
+2. Working directory has no unresolved staged or unstaged changes
 3. Tests pass
 
 If not complete, go back to `spec-implement`.
 
 ---
 
-## Step 1: Validate
+## Step 1: Compare Scope and Simplify
+
+Compare the implementation with the original behavior and user goal before documentation or
+validation. Remove unrequested scope, duplicate concepts, one-consumer abstractions, and custom
+machinery that replaces sufficient platform behavior.
+
+If the implementation faithfully follows an unnecessarily large design, stop and return to
+`spec-plan`. Get approval for the smaller plan before continuing.
+
+Update the finished SDD to describe the smaller result. Replace rejected architecture in the
+normative design and plan instead of preserving it as precedent; mention it only as a rejected
+alternative when that history remains useful.
+
+---
+
+## Step 2: Update Documentation
+
+Check whether README, API documentation, or changelog updates are needed. Make and commit any
+necessary documentation changes through **code-commit** before final validation.
+
+---
+
+## Step 3: Validate
 
 Run validation checks.
 
@@ -67,12 +89,13 @@ go build ./...
 
 ---
 
-## Step 2: Review
+## Step 4: Review
 
-Use the Skill tool to invoke code-review skill for comprehensive code review.
+Invoke the installed **code-review** skill through the harness's skill mechanism for one
+comprehensive review of the final change.
 
 ### What to Review
-- All changed files since feature branch
+- All changed files since the intended base branch's merge base
 - Test coverage
 - Documentation updates
 - No debug code left
@@ -83,41 +106,21 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
 
 ---
 
-## Step 3: Stack Commits
-
-### Workflow
-1. Review current commits: `git log --oneline`
-2. Ensure commits are organized logically
-3. Rebase if needed: `git rebase -i <base-branch>`
-4. Ensure each commit is clean and functional
-
-### Commit Guidelines
-- Each commit should pass tests
-- Use conventional commit format
-- Meaningful commit messages
-
----
-
-## Step 4: Update Documentation
-
-### Check for Updates
-- README changes needed?
-- API documentation updated?
-- Changelog updated?
+## Step 5: Prepare Commits
 
-### If documentation needed
-- Update relevant docs
-- Commit with docs
+Review current commits with `git log --oneline`. Use **code-commit** for any uncommitted work.
+Do not rewrite history by default. If a rebase would materially improve an unpublished stack,
+show the affected range and ask for separate approval before rebasing.
 
 ---
 
-## Step 5: Open the PR
+## Step 6: Prepare the PR
 
-Steps 1-4 (validate, review, stack commits, update docs) must all be complete
+Steps 1-5 (simplification, documentation, validation, review, commits) must all be complete
 before proceeding. **If code-review found blocking or scope-changing issues, stop and return
-to spec-implement to fix them. Do not proceed to Step 5b.**
+to spec-implement to fix them. Do not proceed to Step 6b.**
 
-### Step 5a: Present Completion Summary
+### Step 6a: Present Completion Summary
 
 Before creating the PR, present a summary to the human:
 
@@ -133,7 +136,7 @@ Before creating the PR, present a summary to the human:
 **Ready for PR:** [yes/no]
 ```
 
-### Step 5b: Invoke code-pull-request
+### Step 6b: Invoke code-pull-request
 
 Only when the summary shows **Ready for PR: yes**, invoke the
 [code-pull-request](../code-pull-request/SKILL.md) skill to create the PR. It
@@ -142,7 +145,7 @@ template, generates the body from commits, and opens the PR via `gh` or `glab`.
 
 ### Handoff
 
-> "Implementation complete. [N] commits stacked. Opening PR now."
+> "Implementation complete. [N] commits are ready. PR package ready for approval."
 
 ---
 
@@ -160,3 +163,4 @@ This skill orchestrates other skills:
 - If implementation is still in progress, use spec-implement
 - If tests are failing, go back to spec-implement
 - If review found blocking or scope-changing issues, go back to spec-implement
+- If the implementation follows an unnecessarily large design, go back to spec-plan