pocket-grinding · diff
git:20261007.a2a1e61 to git:20261008.04a46c6
83 added, 76 removed. Audit A to A.
---
name: pocket-grinding
description: BDD-driven feature/fix discovery before any implementation. Use when planning a feature, designing a fix, or exploring options before building. Trigger on "pocket-grinding", "brainstorm", "think through", "plan this", "before we build". Invokes pocket-planning at handoff.
---
# Pocket Grinding
Production-grade requirement discovery using BDD principles. Gathers project context, defines scope, questions from three expert lenses, maps concrete examples to scenarios, validates against existing architecture, and produces a spec ready for delegation.
**Core principle:** Scenarios first, design second. Architecture must be validated before handoff. No implementation until spec is approved.
## When to Use
Trigger this skill when:
- Planning a feature whose shape or requirements aren't yet clear, or that spans multiple files/phases (small, clearly-specified additions → `hotfix`)
- Fixing a non-trivial bug with design implications
- Refactoring a system boundary or changing an API contract
- User says "let's think through", "plan this", "explore options", "before we build"
Do NOT use for:
- Trivial single-line fixes (typo, config value, rename)
- Small, well-understood changes touching only **1–4 files** and resolvable in **1–2 requests** → use `hotfix` instead (Phase 1.5 surfaces this off-ramp mid-flow)
- Work that already has an approved spec
- ## Hard Gates
-
- ```
- GATE 1: NO IMPLEMENTATION until Phase 7 handoff is complete and user approves.
- No code, no scaffolding, no migrations — regardless of perceived simplicity.
-
- GATE 2: NO PHASE 3 without confirmed scope.
- Phase 2 must be user-confirmed before questioning starts.
- Unconfirmed scope = wasted questions.
-
- GATE 3: NO HANDOFF if architecture validation fails (Phase 6).
- Loop back to Phase 5, revise design, re-validate.
-
- GATE 4: POCKET-PLANNING MUST BE INVOKED after user approves spec.
- Pocket-grinding is not done until pocket-planning receives the spec.
- Do not stop at "spec written" — invoke pocket-planning immediately.
+ ## Operating Rules
- GATE 5: EDGE CASE HUNTER MUST RUN before Phase 5 and before handoff.
- After GWT scenarios (Phase 4), dispatch the read-only edge case hunter
- subagent — this is mandatory, not optional. Do NOT offer handoff to
- pocket-planning until the hunter has run and its blocking findings are
- resolved. If you catch yourself moving toward handoff without an edge
- case hunter result, STOP and dispatch it first.
- ```
+ - **Follow the user's stated scope.** Treat clear instructions, corrections, and approvals already given as authorization. Ask only when a consequential product decision remains open; do not ask the user to repeat a decision or choose a numbered option.
+ - **Keep grinding in discovery.** Do not implement product code, scaffolding, or migrations as part of this skill. Hand off an approved or already-authorized spec to pocket-planning for implementation planning.
+ - **Ground validation in evidence.** A checklist item passes only when supported by inspected codebase evidence or, for version-dependent external behavior, current documentation for the relevant version. Record the evidence with the result.
+ - **Keep independent review.** Run the edge-case hunter after writing GWT scenarios. If a review is inconclusive or its dispatch fails, change the prompt or dispatch route and try again; a cycle count alone is not a reason to stop.
+ - **Resolve failed validation with a changed action.** When evidence contradicts a design, revise the proposal and re-check the affected claims. When evidence is missing, inspect another relevant source or record the specific unresolved question; do not mark it PASS by assumption.
+ - **Honor the authorized handoff.** If the user asked for the full spec-to-planning flow, that instruction authorizes the handoff once the required artifacts are ready. Otherwise, present the completed spec and wait for approval before invoking pocket-planning.
---
## Phase 1: Context Scan
**Goal:** Understand the current state before asking a single question.
### Layered Context Protocol
**Project-level** (always scan):
- Stack, frameworks, language versions
- Dependency manifest: read `package.json` / `requirements.txt` / `Cargo.toml` / `go.mod` / `pom.xml` — list installed dependencies relevant to this feature (they are free accelerators; hand-rolling what an installed dep already does is waste)
- Architecture pattern (monolith / microservices / modular monolith)
- Key conventions: naming, folder structure, error handling, logging
**Feature-level** (always scan):
- Which components/modules are affected?
- Related APIs, data models, state management patterns
- Recent commits touching this area: `git log --oneline -10 -- <path>`
- Existing tests covering this area
**Task-level** (when available):
- Prior discussion, tickets, issue comments
- Performance constraints or SLA requirements
- Known edge cases already mentioned by user
### Output of Phase 1
Summarize findings in **3–5 bullets** before proceeding. Do not dump raw file contents — synthesize what matters. Flag unknowns explicitly.
---
## Phase 1.5: Triviality Off-Ramp (Advisory)
**Goal:** Now that the Phase 1 context scan has made task size estimable, check whether the task is small enough that `hotfix` is the better tool — and surface that off-ramp before investing in full discovery.
The full Pocket flow (grinding → planning → structuring → development → review → closing) is heavy ceremony. For genuinely small work it costs more than it returns. Onboarding users often don't know `hotfix` exists and default here for *every* task — this advisory gate names the off-ramp at the moment scope first becomes estimable, so the right tool is suggested without the user having to already know it exists.
### Triviality Heuristic
Estimate from the Phase 1 context scan. The task is **trivial** when BOTH size signals hold:
- Touches only **1–4 files**, AND
- Resolvable in **1–2 requests** (no multi-phase work)
AND none of these complexity signals are present:
- New system, architectural decision, or non-obvious design
- Unclear or contested requirements (the *ask itself* needs exploration, not just the implementation)
- API contract / system-boundary changes
> **"New feature" alone does NOT suppress this gate.** A small, clearly-specified feature addition — e.g. "add a zoom in/out button", "add CSV export" — touches few files, is understood in one request, and only needs a preview + 1–2 refine rounds. That is a `hotfix` candidate, not a grinding one. The discriminator is **requirement clarity + size + architectural impact**, not whether the work is labeled a "feature." Suppress the gate only when the requirement is genuinely unclear or the design decision is architectural.
### Action When Triggered
- Recommend `hotfix`, explain why, then let the user decide:
+ If the user explicitly requested `pocket-grinding`, recommend `hotfix` briefly but continue with grinding unless the user switches. If the skill was selected from a general request, present the choice once and wait:
> "This looks small — roughly **<N> files**, resolvable in 1–2 requests, with no new architecture. The full Pocket flow is likely overkill here. I'd recommend **`hotfix`** instead: it still enforces a brief-plan + subagent-review gate, so accuracy is preserved, but it skips the multi-phase ceremony.
>
> Switch to `hotfix`, or continue with full grinding? (Continue if you expect hidden complexity.)"
**This gate is ADVISORY — non-blocking:**
- If the user continues → proceed to Phase 2 without further friction (power users, or cases with hidden complexity).
- If the user switches → invoke `hotfix` and stop the grinding flow here.
- If the task is **above** the threshold → say nothing about hotfix; proceed silently to Phase 2.
This mirrors the existing `hotfix → pocket-grinding` off-ramp ("Use pocket-grinding instead when: new system, architectural decision, unclear/contested requirements, or work spanning many files/phases"), making the routing relationship **bidirectional**.
---
## Phase 2: Scope + Boundaries
- **Goal:** Lock what's in and out BEFORE questioning starts.
+ **Goal:** Make the proposed scope and boundaries explicit before discovery.
### Scope Definition Template
- Draft and present to user for confirmation:
+ Draft the scope from the user's request and project context. Present it for correction when it adds a consequential assumption or leaves a product decision open. If it preserves the user's stated intent, continue without asking for redundant confirmation.
```
IN-SCOPE:
- <explicit behavior 1>
- <explicit behavior 2>
- OUT-OF-SCOPE (intentionally excluded):
+ OUT-OF-SCOPE (intentionally excluded; write "none identified" if applicable):
- <excluded concern 1>
- <excluded concern 2>
ARCHITECTURE CONSTRAINTS:
- Layers this work may touch: <list>
- Layers this work must NOT touch: <list>
- Patterns that must be followed: <list>
```
**Rules:**
- - If scope is unclear → ask ONE clarifying question, then draft scope
- - If scope spans multiple independent subsystems → decompose first, brainstorm one piece at a time
- - Each sub-scope gets its own brainstorm → spec → pocket-planning cycle
-
- **HARD GATE:** User must explicitly confirm scope. Do not proceed on silence or vague approval.
+ - Ask a focused question only when the answer could materially change scope. Ask one question per message in the conversation; do not depend on a specific question UI or tool.
+ - If scope spans independent subsystems, identify the boundaries and propose a useful sequence. Work through the requested scope without forcing a separate approval cycle for each part.
+ - Do not treat silence as approval for a consequential choice the user has not made. When the user's request already settles the choice, proceed.
---
## Phase 3: Discovery — Three Amigos
**Goal:** Surface requirements, constraints, and risks through structured questioning from three expert lenses.
- Ask **as many questions as needed** until behavior is clear enough to write concrete GWT scenarios. **5 questions is a floor, not a ceiling.** Ask **one question per message**. Rotate across lenses — don't exhaust one lens before touching the others.
+ Use the three lenses to find missing behavior, constraints, and risks. Ask only questions whose answers could change the scenarios, acceptance criteria, or design. There is no minimum question count. Use facts already present in the conversation and codebase; do not ask for them again. Ask one focused question per message and rotate lenses when useful.
**Discovery Sufficiency Gate:** Do NOT advance to Phase 4 until each in-scope behavior has:
- User / actor identified
- Trigger/action identified
- Expected successful outcome identified
- - At least one failure/edge case identified
- - Data/input boundaries identified
+ - At least one relevant failure/edge case identified, or a reason it does not apply
+ - Data/input boundaries identified, or a reason they do not apply
- Acceptance signal identified (how we know it works)
- If any item is missing → keep asking. Do not convert missing behavior into assumptions unless user explicitly says to proceed with an assumption.
+ If an item is missing, first check the conversation and project evidence. Ask the user only when the missing detail is a consequential product decision. For non-blocking details, use an evidence-based default, label it as an assumption, and record the risk in the spec. Never invent a requirement or silently turn a guess into a confirmed behavior.
### Business Lens — WHY + VALUE
Pick the most relevant:
- "What's the user/business problem this solves?"
- "Who is the primary user? What is their goal in this flow?"
- "How will we measure success? What does 'done well' look like in production?"
- "What happens if this isn't built? What's the cost of inaction?"
- "Are there compliance, legal, or timeline constraints we must respect?"
- "What's the priority tradeoff — correctness, performance, UX, or delivery speed?"
### Developer Lens — HOW + FEASIBILITY
Pick the most relevant:
- "Does this fit the current architecture, or does it require a new pattern?"
- "What are the performance constraints? Any latency or throughput SLA?"
- "Are there existing abstractions to reuse, or do we build new ones?"
- "Is there an established library — or an already-installed dependency from the Phase 1 manifest scan — that solves part of this, or must it be custom? Why?"
- "What are the integration points — external APIs, queues, DB schemas, events?"
- "Are there data migration concerns? What's the rollback strategy?"
- "What's the deployment path — feature flag, gradual rollout, hard cutover?"
### QA Lens — WHAT BREAKS + EDGE CASES
Pick the most relevant:
- "What's the worst-case failure mode? What happens to users?"
- "What are the boundary conditions? (empty input, max load, zero state, concurrent access)"
- "Are there race conditions or ordering dependencies to consider?"
- "What external dependencies could fail? How should we degrade gracefully?"
- "What existing tests might break? What new tests are non-negotiable?"
- "Are there security implications? (auth, authorization, input validation, data exposure)"
### Iteration Rules
- - After 5 questions: run the Discovery Sufficiency Gate — if behavior is still unclear, continue asking
- - If an answer reveals new unknowns → ask follow-up questions until the specific behavior is clear
- - If user says "I don't know" → ask whether to (a) choose a safe default, (b) document an assumption, or (c) exclude that behavior from scope
- - Never ask two questions in one message
- - Do not advance because a question count was reached; advance only when GWT scenarios can be written with concrete Given/When/Then values
+ - Re-run the Discovery Sufficiency Gate whenever new information changes a behavior; do not wait for a question-count threshold.
+ - If an answer reveals a consequential unknown, ask a focused follow-up. Otherwise record the uncertainty and proceed with a clearly labeled assumption.
+ - If the user says "I don't know," recommend a safe default when evidence supports one. Ask the user only if the choice changes product behavior, scope, or risk tolerance.
+ - Ask one question per message. Do not call a dedicated question UI/tool unless the environment supports it and the user has not asked to avoid it.
+ - Advance when the in-scope behaviors can be written as concrete Given/When/Then scenarios, not when a question count is reached.
---
## Phase 4: Formulation — Example Mapping
**Goal:** Convert discovery answers into concrete, testable scenarios.
### Example Mapping Format
For each key behavior identified in Phase 3:
```
STORY:
As a <who>, I want <what>, so that <why>
RULES (business rules / invariants governing this story):
Rule 1: <constraint or invariant>
Rule 2: <constraint or invariant>
EXAMPLES (one or more concrete instances per rule):
Rule 1 → Example A: <specific input → expected output>
Rule 1 → Example B: <edge case input → expected output>
Rule 2 → Example C: <specific input → expected output>
OPEN QUESTIONS (unresolved — must be answered or documented as assumption):
? <question 1>
? <question 2>
```
### Given-When-Then Scenarios
Convert each example into a GWT scenario:
```
Scenario: <descriptive name>
Given <initial context / precondition>
When <specific action or event>
Then <expected outcome>
And <additional outcome if needed>
```
**Rules for good scenarios:**
- One behavior per scenario — don't combine two behaviors
- Concrete values, not generic placeholders ("a user with role=editor", not "some user")
- Always include failure scenarios: `Given invalid input, When submitted, Then error X is returned`
- Cover: happy path, edge cases, failure paths, concurrent cases if relevant
### Open Questions Protocol
1. List all open questions surfaced during mapping
2. Classify each as:
- **BLOCKING** — required to define behavior / GWT / acceptance criteria
- **NON-BLOCKING** — implementation detail, risk, or future refinement
3. Resolve all BLOCKING questions via follow-up questions before Phase 5
4. NON-BLOCKING questions may be documented as **assumption + risk** in the handoff package
**Hard rule:** Never write GWT scenarios with vague placeholders to bypass unanswered behavioral questions.
- ### Edge Case Hunter Review (GATE 5 — MANDATORY)
+ ### Edge Case Hunter Review (Required)
- **This is the Phase 4→5 transition step. It is not optional and must not be skipped — see GATE 5 in Hard Gates.** The moment GWT scenarios are written, your next action is to dispatch the edge case hunter — before anything else, and well before any mention of handoff.
+ Run this review after writing GWT scenarios and before proposing designs. It is an independent review step; do not replace it with your own self-review.
- Dispatch a read-only edge case hunter subagent to review the Phase 4 stories, rules, examples, and GWT scenarios.
+ Dispatch a read-only subagent named `edge-case-hunter` to review the Phase 4 stories, rules, examples, and GWT scenarios.
→ Load `references/edge-case-hunter-prompt.md` for the full dispatch prompt.
**Purpose:** catch missing in-scope edge cases and blocking behavior ambiguity before design proposals.
- **Gate:**
- - Status = `Clear` → proceed to Phase 5
- - Status = `Needs Clarification` → ask blocking clarification questions one at a time, update scenarios, re-run once if material behavior changed
- - Do NOT proceed to design while blocking behavior questions remain unresolved
- - Do NOT offer handoff to pocket-planning if this step has not run — that is a GATE 5 violation
+ **Next action:**
+ - `Clear` → proceed to Phase 5.
+ - `Needs Clarification` → resolve consequential behavior questions, update the affected scenarios, and run a focused independent review of the changes.
+ - Review is inconclusive or dispatch fails → improve the review prompt or try another available subagent route. Do not repeat an unchanged attempt or treat a retry count as a terminal limit.
+ - If no independent reviewer can run, state that limitation and leave the review status unresolved. Do not claim it passed; ask the user only if they want to proceed without the required independent review.
+ - Do not move to design or handoff while blocking behavior questions remain unresolved.
---
## Phase 5: Design Proposals
**Goal:** Propose 2–3 options. Design must emerge FROM Phase 4 scenarios — never before them.
### Proposal Format
```
Option A: <name>
Summary: <1–2 sentences>
Scenarios satisfied: <list GWT scenarios this handles>
Scenarios at risk: <list any it handles partially or poorly>
Tradeoffs:
+ <advantage>
- <disadvantage>
Risk: <biggest concern with this option>
Option B: <name>
...
Recommendation: Option <X>
Reasoning: <cite specific scenarios that make this the strongest choice>
```
**Rules:**
- Each option validated against Phase 4 scenarios explicitly
- An option that fails critical scenarios must be flagged, not softened
- Recommendation must cite scenarios, not just preference
- **Build-vs-buy:** for commodity problems (crypto, auth, parsing, retry/backoff, date/time, validation, caching, …) at least one option must be library-based — prefer dependencies already installed (Phase 1 manifest scan). If no library option is proposed, state explicitly why none is viable. Never hand-roll crypto or auth without naming the rejected library and the reason.
- - Unknown library capability → quick check first (context7 / web search — see pocket-pitching's spike protocol), don't guess
+ - For every external library, framework, API, or platform capability that materially affects an option, verify the behavior before recommending it. Identify the exact installed or proposed version from the manifest/lockfile. Use Context7 MCP in order: `resolve-library-id`, then `query-docs` with the matching version when available. If Context7 has no relevant result, check the vendor's official documentation or release notes with web search. Do not rely on memory or latest-version docs when the project uses a different version; record the source, version, and finding.
---
## Phase 6: Architecture Validation
- **Goal:** Confirm the chosen design does not violate constraints from Phase 2.
+ **Goal:** Verify the recommended design against the actual codebase, stated constraints, and current version-matched external documentation.
+ Do not mark this phase complete from the Phase 1 summary or a checklist alone. Re-open the relevant source files and verify each material claim directly.
+
+ ### Validation Procedure
+
+ 1. **List the claims to verify.** Include the recommended design, affected GWT scenarios, architecture constraints, integration points, dependencies, and any assumptions that could change implementation.
+ 2. **Inspect the codebase.** Read the affected modules and their callers, interfaces, data models or schemas, configuration, tests, migrations, and existing patterns. Use repository search to find all relevant references; do not infer that a pattern is absent from one empty search result.
+ 3. **Verify external behavior.** For each version-dependent library/framework/API/platform claim, identify the version in the lockfile or the version proposed for adoption. Use Context7 MCP's `resolve-library-id` followed by `query-docs`, selecting the matching version ID when available. If Context7 is unavailable or inconclusive, use the vendor's versioned documentation, API reference, or release notes. For standards or other changing external constraints, use current primary sources. Record the direct source, version, and publication or access date.
+ 4. **Compare evidence with the spec.** For each claim, state whether the code or documentation supports it, contradicts it, or leaves it unresolved. Use file paths and symbols (or line references where stable) for code evidence, and direct source links plus version/date for external evidence.
+ 5. **Resolve findings.** Revise the proposal when evidence contradicts it, then re-check the changed claims. If a source is unavailable or inconclusive, try a different relevant source or mode. Do not repeat an unchanged search or stop solely because a retry count was reached.
+
+ Use Context7 for library documentation; it cannot validate this repository's internal architecture. Use the codebase for internal structure and official current sources for external behavior. If a claim cannot be verified after distinct sources, mark it `UNVERIFIED`, explain its impact, and carry it as an open question or explicit assumption. Never mark it `PASS` by inference.
+
### Quick Validation Checklist
- ```
- [ ] Respects layer boundaries defined in Phase 2?
- [ ] Follows existing patterns found in Phase 1 context scan?
- [ ] No new dependencies that violate architecture constraints?
- [ ] Build-vs-buy considered — not hand-rolling a commodity problem an installed or established dependency already solves?
- [ ] Rollback / undo strategy is defined?
- [ ] No silent data migrations or breaking changes to contracts?
- [ ] Performance characteristics acceptable for this layer?
- [ ] No security regressions introduced?
- ```
+ For each applicable item, record `PASS`, `FAIL`, `UNVERIFIED`, or `N/A` with evidence. Use `N/A` only with a reason. A `PASS` requires specific supporting evidence; an unchecked box is not a pass.
- **PASS** (all checked) → Proceed to Phase 7
- **FAIL** (any unchecked) → Document which constraint is violated → loop back to Phase 5
+ | Check | Evidence to inspect | Result | Evidence / finding |
+ |---|---|---|---|
+ | Respects stated layer and module boundaries | Relevant modules, imports, interfaces, and constraints | | |
+ | Fits existing patterns and contracts | Callers, models/schemas, APIs/events, tests, and migrations | | |
+ | Dependencies and build-vs-buy are justified | Manifest/lockfile and version-matched official docs | | |
+ | Rollback, compatibility, and data changes are defined | Migration, deployment, and contract behavior | | |
+ | Performance and security risks are addressed | Relevant code paths, tests, and current requirements | | |
- For complex systems, major refactors, or ambiguous constraint violations:
+ **PASS** → Every applicable material claim is supported and no blocking finding remains.
+ **FAIL** → Evidence contradicts the proposal; revise Phase 5 and re-check affected claims.
+ **UNVERIFIED** → Evidence is missing or inconclusive; try another relevant source, then document the exact gap and its impact.
+ **N/A** → Explain why the check does not apply.
+
+ Do not describe the design as fully validated while a material claim remains
+ `UNVERIFIED`. Resolve it with another source, revise the design to remove the
+ dependency, or present the risk for the user's decision. Non-material gaps may be
+ carried as explicit assumptions with a mitigation.
+
+ For complex systems, major refactors, or ambiguous constraint violations, also load the deep protocol. It supplements this evidence-based procedure; it does not replace codebase or documentation checks:
→ Load `references/architecture-validation.md`
---
## Phase 7: Handoff Package
**Goal:** Produce a complete, pocket-planning-ready spec. User must approve before invoking.
### Save Spec Document
Save to this exact directory structure:
```
docs/pocket/spec/
└── YYYY-MM-DD-kebab-slug/
└── topic-name.md
```
Example: `docs/pocket/spec/2026-05-06-user-auth-refactor/session-flow.md`
- Root: always `docs/pocket/spec/` — do NOT use `docs/plans/` or other paths
- Dir: `YYYY-MM-DD-kebab-slug` (today's date + hyphenated feature name)
- File: descriptive topic name, lowercase hyphenated
- Multiple files per dir allowed if session covers distinct sub-topics
For full spec document template with all sections:
→ Load `references/spec-template.md`
### Acceptance Criteria (always inline in handoff)
```
ACCEPTANCE CRITERIA — <feature/fix name>
Date: YYYY-MM-DD | Scope confirmed: yes
Rule: <rule 1 name>
✓ Given <context>, When <action>, Then <expected outcome>
✓ Given <edge case>, When <action>, Then <outcome>
✗ Given <invalid input>, When <action>, Then <specific error>
Rule: <rule 2 name>
✓ Given <context>, When <action>, Then <expected outcome>
OPEN QUESTIONS (risks if unresolved):
- <question> → assumed: <assumption made>
OUT-OF-SCOPE (remind pocket-planning):
- <excluded concern>
```
- ### Pre-Handoff Checkpoint (GATE 5 backstop)
+ ### Pre-Handoff Checkpoint
- Before presenting the User Approval Gate, verify the GATE 5 requirement was met:
+ Before handoff, verify that the independent review and evidence-based architecture validation are complete:
```
- [ ] Edge case hunter was dispatched after Phase 4 GWT scenarios
- [ ] Its findings were reviewed; all BLOCKING findings are resolved
- [ ] Scenarios/acceptance criteria reflect any edge cases it surfaced
+ [ ] Edge-case hunter reviewed the Phase 4 GWT scenarios
+ [ ] Blocking review findings are resolved and reflected in the scenarios
+ [ ] Phase 6 validation evidence is recorded in the spec
+ [ ] All blocking architecture findings are resolved
+ [ ] Any remaining material unverified claim and its impact are explicit for the user
```
- If the edge case hunter never ran → **STOP. Do not offer handoff.** Loop back to
- Phase 4's Edge Case Hunter Review, dispatch it now, resolve blocking findings, then
- return here. This checkpoint is the last line of defense against the GATE 5 bypass.
+ If any item is incomplete, return to the relevant phase and take the next available
+ verification or review step. If an independent reviewer or required evidence source
+ is unavailable after trying alternatives, state the exact gap and impact. Ask the
+ user only when their decision is required to accept or exclude that risk.
- ### User Approval Gate
+ ### User Approval and Handoff
> "Spec written to `docs/pocket/spec/<path>`. Acceptance criteria above — anything to adjust before I hand this to pocket-planning?"
- Wait for confirmation. Apply any changes.
+ If the user has not already authorized the spec-to-planning handoff, wait for
+ approval and apply requested changes. A clear earlier instruction to complete that
+ flow counts as authorization; do not ask for the same approval again. If the user
+ asked only for a spec, stop after delivering it unless they authorize planning.
### Neutral spec approval handoff
- After the user approves the spec, emit the neutral lifecycle event before invoking pocket-planning. The event records local artifact references; it does not require an external consumer and does not block the local planning handoff when no consumer is installed.
+ After the user approves or has already authorized the spec handoff, emit the neutral lifecycle event before invoking pocket-planning. The event records local artifact references; it does not require an external consumer and does not block the local planning handoff when no consumer is installed.
```bash
pocketto-pi lifecycle transition <spec_dir> spec-approved --artifact spec:<kind>:<relative-path>:<sha256> --json --contract 3
```
Pass the approved spec as a spec-root artifact reference. Core records the event and its `artifact_refs` in `lifecycle.json`; artifact contents are not copied into the event. Preserve the command result with the plan handoff context.
### Invoke pocket-planning (MANDATORY)
**DO NOT STOP AFTER USER APPROVAL.**
**Step 1 — Identify invocation method:**
Determine how skills or agents are dispatched in your current environment.
- In Claude Code: use the `Skill` tool to invoke `pocket-planning`.
- In other agent platforms: use your platform's skill or agent dispatch mechanism.
- If no dispatch mechanism exists: load and follow the `pocket-planning` skill directly in this session.
**Step 2 — Load pocket-planning skill:**
- Load the `pocket-planning` skill (already loaded at session start) and follow it completely.
+ Load the `pocket-planning` skill if it is not already available, then follow it completely.
Do NOT skip phases. Do NOT stop at Phase 1.
**Step 3 — Pass this context to pocket-planning:**
- Spec file path: `docs/pocket/spec/<path>`
- Acceptance criteria (full GWT list from Phase 4)
- Architecture constraints from Phase 2
- Open questions / assumptions logged in Phase 4
- Design decision from Phase 5
**This is not optional.** Pocket-grinding is incomplete until pocket-planning has received the spec and begun Phase 0 (Preflight).
**Verification:** After invoking pocket-planning, confirm it has:
- [ ] Read the spec file
- [ ] Started Phase 0 codebase scan
- [ ] Produced a Preflight Summary
If pocket-planning did not start → re-invoke with explicit instruction to begin Phase 0.
---
## Reference Triggers
| Reference | When to Load |
|-----------|--------------|
| `references/architecture-validation.md` | Phase 6: complex systems, ambiguous constraint violations, major refactors needing deep validation |
| `references/spec-template.md` | Phase 7: writing full spec doc to disk |
| `references/edge-case-hunter-prompt.md` | Phase 4: after GWT scenarios, before design proposals — find missing in-scope edge cases |