@juicesharp/rpiv-pi 0.4.0

package/skills/create-handoff/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: create-handoff
+description: Create context-preserving handoff documents for session transitions. Compacts essential context into concise documents. Use when context is getting large or before starting a fresh session.
+argument-hint: [description]
+allowed-tools: Read, Write, Bash(git *), Glob, Grep
+disable-model-invocation: true
+---
+
+# Create Handoff
+
+You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also **concise**. The goal is to compact and summarize your context without losing any of the key details of what you're working on.
+
+
+## Process
+### 1. Filepath & Metadata
+Use the following information to understand how to create your document:
+    - create your file under `thoughts/shared/handoffs/YYYY-MM-DD_HH-MM-SS_description.md`, where:
+        - YYYY-MM-DD is today's date
+        - HH-MM-SS is the hours, minutes and seconds based on the current time, in 24-hour format (i.e. use `13-00-00` for `1:00 pm`)
+        - description is a brief kebab-case description
+     - Repository name: from git root basename, or current directory basename if not a git repo
+     - Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly)
+     - Researcher: use the User from the git context injected at the start of the session (fallback: "unknown")
+     - If metadata unavailable: use "unknown" for commit/branch
+    - Examples:
+        - `thoughts/shared/handoffs/2025-01-08_13-55-22_create-context-compaction.md`
+
+### 2. Handoff writing.
+using the above conventions, write your document. use the defined filepath, and the following YAML frontmatter pattern. Use the metadata gathered in step 1, Structure the document with YAML frontmatter followed by content:
+
+Use the following template structure:
+```markdown
+---
+date: [Current date and time with timezone in ISO format]
+researcher: [Researcher name from thoughts status]
+git_commit: [Current commit hash]
+branch: [Current branch name]
+repository: [Repository name]
+topic: "[Feature/Task Name] [Work Type]" # Customize work type: Implementation Strategy, Bug Fix, Research, Feature Implementation, etc.
+tags: [implementation, strategy, relevant-component-names]
+status: complete
+last_updated: [Current date in YYYY-MM-DD format]
+last_updated_by: [Researcher name]
+type: [work_type] # Options: implementation_strategy, bug_fix, research, refactoring, feature_development, etc.
+---
+
+# Handoff: {very concise description}
+
+## Task(s)
+{description of the task(s) that you were working on, along with the status of each (completed, work in progress, planned/discussed). If you are working on an implementation plan, make sure to call out which phase you are on. Make sure to reference the plan document and/or research document(s) you are working from that were provided to you at the beginning of the session, if applicable.}
+
+## Critical References
+{List any critical specification documents, architectural decisions, or design docs that must be followed. Include only 2-3 most important file paths. Leave blank if none.}
+
+## Recent changes
+{describe recent changes made to the codebase that you made in file:line syntax}
+
+## Learnings
+{describe important things that you learned - e.g. patterns, root causes of bugs, or other important pieces of information someone that is picking up your work after you should know. consider listing explicit file paths.}
+
+## Artifacts
+{ an exhaustive list of artifacts you produced or updated as filepaths and/or file:line references - e.g. paths to feature documents, implementation plans, etc that should be read in order to resume your work.}
+
+## Action Items & Next Steps
+{ a list of action items and next steps for the next agent to accomplish based on your tasks and their statuses}
+
+## Other Notes
+{ other notes, references, or useful information - e.g. where relevant sections of the codebase are, where relevant documents are, or other important things you learned that you want to pass on but that don't fall into the above categories}
+```
+---
+
+### 3. Approve
+Save the document.
+
+Once this is completed, you should respond to the user with the template between <template_response></template_response> XML tags. do NOT include the tags in your response.
+
+<template_response>
+Handoff created! You can resume from this handoff in a new session with the following command:
+
+```bash
+/skill:resume-handoff thoughts/shared/handoffs/YYYY-MM-DD_HH-MM-SS_description.md
+```
+
+Replace the path with your actual handoff file path.
+</template_response>
+
+---
+## Additional Notes & Instructions
+- **more information, not less**. This is a guideline that defines the minimum of what a handoff should be. Always feel free to include more information if necessary.
+- **be thorough and precise**. include both top-level objectives, and lower-level details as necessary.
+- **avoid excessive code snippets**. While a brief snippet to describe some key change is important, avoid large code blocks or diffs; do not include one unless it's necessary (e.g. pertains to an error you're debugging). Prefer using `/path/to/file.ext:line` references that an agent can follow later when it's ready, e.g. `packages/dashboard/src/app/dashboard/page.tsx:12-24`

package/skills/design/SKILL.md

@@ -0,0 +1,416 @@
+---
+name: design
+description: Design features through iterative vertical-slice decomposition and progressive code generation with developer micro-checkpoints. For complex multi-component features touching 6+ files across multiple layers. Produces design artifacts in thoughts/shared/designs/. Always requires a research artifact from discover → research, or a solutions artifact from explore.
+argument-hint: [research artifact path]
+---
+
+# Design
+
+You are tasked with designing how code will be shaped for a feature or change. This iterative variant decomposes features into vertical slices and generates code slice-by-slice with developer micro-checkpoints between slices. The design artifact feeds directly into plan, which sequences it into phases.
+
+**How it works**:
+- Read input and key source files into context (Step 1)
+- Spawn targeted research agents for depth analysis (Step 2)
+- Identify ambiguities — triage into simple decisions and genuine ambiguities (Step 3)
+- Holistic self-critique — review the combined design for gaps and contradictions (Step 4)
+- Developer checkpoint — resolve genuine ambiguities one at a time (Step 5)
+- Decompose into vertical slices holistically before generating code (Step 6)
+- Generate code slice-by-slice with developer micro-checkpoints (Step 7)
+- Verify cross-slice integration consistency (Step 8)
+- Finalize the design artifact (Step 9)
+- Review and iterate with the developer (Step 10)
+
+The final artifact is plan-compatible.
+
+## Step 1: Input Handling
+
+When this command is invoked:
+
+1. **Read research artifact**:
+
+   **Research artifact provided** (argument contains a path to a `.md` file in `thoughts/`):
+   - Read the research artifact FULLY using the Read tool WITHOUT limit/offset
+   - Extract: Summary, Code References, Integration Points, Architecture Insights, Developer Context, Open Questions
+   - **Read the key source files from Code References** into the main context — especially hooks, shared utilities, and integration points the design will depend on. Read them FULLY. This ensures you have complete understanding before proceeding.
+   - These become starting context — no need to re-discover what exists
+   - Research Developer Context Q/As = inherited decisions (record in Decisions, never re-ask); Open Questions = starting ambiguity queue, filtered by dimension in Step 3
+   - If a discover artifact is also provided, read it for additional discovery context
+
+   **No arguments provided**:
+   ```
+   I'll design a feature iteratively from a research artifact. Please provide:
+
+   `/skill:design [research artifact] [discover] [task description]`
+
+   Research artifact is required. Discover and task description are optional, in any order.
+   ```
+   Then wait for input.
+
+2. **Read any additional files mentioned** — tickets, related designs, existing implementations. Read them FULLY before proceeding.
+
+## Step 2: Targeted Research
+
+This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
+
+1. **Spawn parallel research agents** using the Agent tool:
+
+   - Use **codebase-pattern-finder** to find existing implementations to model after — the primary template for code shape
+   - Use **codebase-analyzer** to understand HOW integration points work in detail
+   - Use **integration-scanner** to map the wiring surface — inbound refs, outbound deps, config/DI/event registration
+   - Use **precedent-locator** to find similar past changes in git history — what commits introduced comparable features, what broke, and what lessons apply to this design
+
+   **Novel work** (new libraries, first-time patterns, no existing codebase precedent):
+   - Add **web-search-researcher** for external documentation, API references, and community patterns
+   - Instruct it to return LINKS with findings — include those links in the final design artifact
+
+   Agent prompts should focus on:
+   - "Find the implementation pattern I should model after for [feature type]"
+   - "How does [integration point] work in detail — show me the wiring"
+   - "What connects to [component] — inbound refs, outbound deps, config"
+
+   NOT: "Find all files related to X" — that's discovery's job, upstream of this skill.
+
+2. **Read all key files identified by agents** into the main context — especially the pattern templates you'll model after.
+
+3. **Wait for ALL agents to complete** before proceeding.
+
+4. **Analyze and verify understanding**:
+   - Cross-reference research findings with actual code read in Step 1
+   - Identify any discrepancies or misunderstandings
+   - Note assumptions that need verification
+   - Determine true scope based on codebase reality
+
+## Step 3: Identify Ambiguities — Dimension Sweep
+
+Walk Step 2 findings, inherited research Q/As, and carried Open Questions through six architectural dimensions that map 1:1 to `plan` extract sections — the sweep guarantees downstream completeness. Add **migration** as a seventh dimension only if the feature changes persisted schema.
+
+- **Data model** — types, schemas, entities
+- **API surface** — signatures, exports, routes
+- **Integration wiring** — mount points, DI, events, config
+- **Scope** — in / explicitly deferred
+- **Verification** — tests, assertions, risk-bearing behaviors
+- **Performance** — load paths, caching, N+1 risks
+
+For each dimension, classify findings as **simple decisions** (one valid option, obvious from codebase — record in Decisions with `file:line` evidence, do not ask) or **genuine ambiguities** (multiple valid options, conflicting patterns, scope questions, novel choices — queue for Step 5). Inherited research Q/As land as simple; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+
+**Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
+
+## Step 4: Holistic Self-Critique
+
+Before presenting ambiguities to the developer, review the combined design picture holistically. Step 3 triages findings individually — this step checks whether they fit together as a coherent whole.
+
+**Prompt yourself:**
+- What's inconsistent, missing, or contradictory across the research findings, resolved decisions, and identified ambiguities?
+- What edge cases or failure modes aren't covered by any ambiguity or decision?
+- Do any patterns from different agents conflict when combined?
+
+**Areas to consider** (suggestive, not a checklist):
+- Requirement coverage — is every requirement from Step 1 addressed by at least one decision or ambiguity?
+- Cross-cutting concerns — do error handling, state management, or performance span multiple ambiguities without being owned by any?
+- Pattern coherence — do the simple decisions from Step 3 still hold when viewed together, or does a combination reveal a conflict?
+- Ambiguity completeness — did Step 3 miss a genuine ambiguity by treating a multi-faceted issue as simple?
+
+**Remediation:**
+- Issues you can resolve with evidence: fix in-place — reclassify simple decisions as genuine ambiguities, or resolve a genuine ambiguity as simple if holistic review provides clarity. Note what changed.
+- Issues that need developer input: add as new genuine ambiguities to the Step 5 checkpoint queue.
+- If no issues found: proceed to Step 5 with the existing ambiguity set.
+
+## Step 5: Developer Checkpoint
+
+Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix so the developer knows their input is needed. Each question must:
+- Reference real findings with `file:line` evidence
+- Present concrete options (not abstract choices)
+- Pull a DECISION from the developer, not confirm what you already found
+
+**Question patterns by ambiguity type:**
+
+- **Pattern conflict**: "Found 2 patterns for [X]: [pattern A] at `file:line` and [pattern B] at `file:line`. They differ in [specific way]. Which should the new [feature] follow?"
+- **Missing pattern**: "No existing [pattern type] in the codebase. Options: (A) [approach] modeled after [external reference], (B) [approach] extending [existing code at file:line]. Which fits the project's direction?"
+- **Scope boundary**: "The [research/description] mentions both [feature A] and [feature B]. Should this design cover both, or just [feature A] with [feature B] deferred?"
+- **Integration choice**: "[Feature] can wire into [point A] at `file:line` or [point B] at `file:line`. [Point A] matches the [existing pattern] pattern. Agree, or prefer [point B]?"
+- **Novel approach**: "No existing [X] in the project. Options: (A) [library/pattern] — [evidence/rationale], (B) [library/pattern] — [evidence/rationale]. Which fits?"
+
+**Critical rules:**
+- Ask ONE question at a time. Wait for the answer before asking the next.
+- Lead with the most architecturally significant ambiguity.
+- Every answer becomes a FIXED decision — no revisiting unless the developer explicitly asks.
+
+**Choosing question format:**
+
+- **`ask_user_question` tool** — when your question has 2-4 concrete options from code analysis (pattern conflicts, integration choices, scope boundaries, priority overrides). The user can always pick "Other" for free-text. Example:
+
+  > Use the `ask_user_question` tool with the following question: "Found 2 mapping approaches — which should new code follow?". Header: "Pattern". Options: "Manual mapping (Recommended)" (Used in OrderService (src/services/OrderService.ts:45) — 8 occurrences); "AutoMapper" (Used in UserService (src/services/UserService.ts:12) — 2 occurrences).
+
+- **Free-text with ❓ Question: prefix** — when the question is open-ended and options can't be predicted (discovery, "what am I missing?", corrections). Example:
+  "❓ Question: Integration scanner found no background job registration for this area. Is that expected, or is there async processing I'm not seeing?"
+
+**Batching**: When you have 2-4 independent questions (answers don't depend on each other), you MAY batch them in a single `ask_user_question` call. Keep dependent questions sequential.
+
+**Classify each response:**
+
+**Decision** (e.g., "use pattern A", "yes, follow that approach"):
+- Record in Developer Context. Fix in Decisions section.
+
+**Correction** (e.g., "no, there's a third option you missed", "check the events module"):
+- Spawn targeted rescan: **codebase-analyzer** on the new area (max 1-2 agents).
+- Merge results. Update ambiguity assessment.
+
+**Scope adjustment** (e.g., "skip the UI, backend only", "include tests"):
+- Record in Developer Context. Adjust scope.
+
+**After all ambiguities are resolved**, present a brief design summary (under 15 lines):
+
+```
+Design: [feature name]
+Approach: [1-2 sentence summary of chosen architecture]
+
+Decisions:
+- [Decision 1]: [choice] — modeled after `file:line`
+- [Decision 2]: [choice]
+- [Decision 3]: [choice]
+
+Scope: [what's in] | Not building: [what's out]
+Files: [N] new, [M] modified
+```
+
+Use the `ask_user_question` tool to confirm before proceeding. Question: "[Summary from design brief above]. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed (Recommended)" (Decompose into vertical slices, then generate code slice-by-slice); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).
+
+## Step 6: Feature Decomposition
+
+After the design summary is confirmed, decompose the feature into vertical slices. Each slice is a self-contained unit: types + implementation + wiring for one concern.
+
+1. **Decompose holistically** — define ALL slices, dependencies, and ordering before generating any code:
+
+   ```
+   Feature Breakdown: [feature name]
+
+   Slice 1: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
+     Depends on: nothing (foundation)
+
+   Slice 2: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
+     Depends on: Slice 1
+
+   Slice 3: [name] — [what this slice delivers]
+     Files: path/to/file.ext (NEW)
+     Depends on: Slice 2
+   ```
+
+2. **Slice properties**:
+   - End-to-end vertical: each slice is a complete cross-section of one concern (types + impl + wiring)
+   - ~512-1024 tokens per slice (maps to individual file blocks)
+   - Sequential: each builds on the previous (never parallel)
+   - Foundation first: types/interfaces always Slice 1
+
+3. **Confirm decomposition** using the `ask_user_question` tool. Question: "[N] slices for [feature]. Slice 1: [name] (foundation). Slices 2-N: [brief]. Approve decomposition?". Header: "Slices". Options: "Approve (Recommended)" (Proceed to slice-by-slice code generation); "Adjust slices" (Reorder, merge, or split slices before generating); "Change scope" (Add or remove files from the decomposition).
+
+4. **Create skeleton artifact** — immediately after decomposition is approved:
+   - Determine metadata: filename `thoughts/shared/designs/YYYY-MM-DD_HH-MM-SS_topic.md`, repository name from git root, branch and commit from the git context injected at the start of the session (fallbacks: "no-branch" / "no-commit"), designer from the injected User (fallback: "unknown")
+   - Write skeleton using the Write tool with `status: in-progress` in frontmatter
+   - **Include all prose sections filled** from Steps 1-5: Summary, Requirements, Current State Analysis, Scope, Decisions, Desired End State, File Map, Ordering Constraints, Verification Notes, Performance Considerations, Migration Notes, Pattern References, Developer Context, References
+   - **Architecture section**: one `### path/to/file.ext — NEW/MODIFY` heading per file from the decomposition, with empty code fences as placeholders
+   - **Design History section**: list all slices with `— pending` status
+   - This is the living artifact — all subsequent writes use the Edit tool
+
+   **Artifact template sections** (all required in skeleton):
+
+   - **Frontmatter**: date, designer, git_commit, branch, repository, topic, tags, `status: in-progress`, research_source, last_updated, last_updated_by
+   - **# Design: [Feature Name]**
+   - **## Summary**: 2-3 sentences — what we're building and the chosen architectural approach. Settled decision, not a discussion.
+   - **## Requirements**: Bullet list from ticket, research, or developer input.
+   - **## Current State Analysis**: What exists now, what's missing, key constraints. Include `### Key Discoveries` with `file:line` references, patterns to follow, constraints to work within.
+   - **## Scope**: `### Building` — concrete deliverables. `### Not Building` — developer-stated exclusions AND likely scope-creep vectors (alternative architectures not chosen, nearby code that looks related but shouldn't be touched).
+   - **## Decisions**: `###` per decision. Complex: Ambiguity → Explored (Option A/B with `file:line` + pro/con) → Decision. Simple: just state decision with evidence.
+   - **## Architecture**: `###` per file with NEW/MODIFY label. Empty code fences in skeleton (filled in Step 7d). NEW files get full implementation. MODIFY files get only modified/added code — no "Current" block.
+   - **## Desired End State**: Usage examples showing the feature in use from a consumer's perspective — concrete code, not prose.
+   - **## File Map**: `path/to/file.ext  # NEW/MODIFY — purpose` per line.
+   - **## Ordering Constraints**: What must come before what. What can run in parallel.
+   - **## Verification Notes**: Carry forward from research — known risks, build/test warnings, precedent lessons. Format as verifiable checks (commands, grep patterns, visual inspection). plan converts these to success criteria.
+   - **## Performance Considerations**: Any performance implications or optimizations.
+   - **## Migration Notes**: If applicable — existing data, schema changes, rollback strategy, backwards compatibility. Empty if not applicable.
+   - **## Pattern References**: `path/to/similar.ext:line-range` — what pattern to follow and why.
+   - **## Developer Context**: Record questions exactly as asked during checkpoint, including `file:line` evidence. For iterative variant: also record micro-checkpoint interactions from Step 7c.
+   - **## Design History**: Slice approval/revision log. `- Slice N: [name] — pending/approved as generated/revised: [what changed]`. plan ignores this section.
+   - **## References**: Research artifacts, tickets, similar implementations.
+
+   **Architecture format in skeleton**:
+   - **NEW files**: heading + empty code fence (filled with full implementation in Step 7d)
+   - **MODIFY files**: heading with `file:line-range` + empty code fence (filled with only the modified code in Step 7d — no "Current" block, the original is on disk)
+
+## Step 7: Generate Slices (Iterative)
+
+Generate code one slice at a time. Each slice sees the fixed code from all previous slices.
+
+**For each slice in the decomposition (sequential order):**
+
+### 7a. Generate slice code (internal)
+
+Generate complete, copy-pasteable code for every file in this slice — but **hold it for the artifact, do NOT present full code to the developer**. The developer sees a condensed review in 7c; the full code goes into the artifact in 7d.
+
+- **New files**: complete code — imports, types, implementation, exports. Follow the pattern template from Step 2.
+- **Modified files**: read current file FULLY, generate only the modified/added code scoped to changed sections (no full "Current" block — the original is on disk)
+- **Test files**: complete test suites following project patterns
+- **Wiring**: show where new code hooks into existing code
+
+If additional context is needed, spawn a targeted **codebase-analyzer** agent.
+
+No pseudocode, no TODOs, no placeholders — the code must be copy-pasteable by implement.
+
+**Context grounding** (after slice 2): Before generating, re-read the artifact's Architecture section for files this slice touches. The artifact is the source of truth — generate code that extends what's already there, not what you remember from conversation.
+
+### 7b. Self-verify slice
+
+Before presenting to the developer, cross-check this slice and produce a structured summary:
+
+```
+Self-verify Slice N:
+- Decisions: [OK / VIOLATION: decision X — fix applied]
+- Cross-slice: [OK / CONFLICT: file X has inconsistent types — fix applied]
+- Research: [OK / WARNING: constraint Y not satisfied — fix applied]
+```
+
+If violations found: fix in-place before presenting. Include the self-verify summary in the 7c checkpoint presentation.
+
+### 7c. Developer micro-checkpoint
+
+Present a **condensed review** of the slice — NOT the full generated code. The developer reviews the design shape, not every line. For each file in the slice, show:
+
+1. **Summary** (1-2 sentences): what changed, what pattern used, what it connects to
+2. **Signatures**: type/interface definitions, exported function signatures with parameter and return types
+3. **Key code blocks**: factory calls, wiring, non-obvious logic — the interesting parts that show the design decision in action
+
+**Omit**: boilerplate, import lists, full function bodies, obvious implementations.
+**MODIFY files**: focused diff (`- old` / `+ new`) with ~3 lines context. **Test files**: test case names only.
+
+**If the developer asks to see full code**, show it inline — exception, not default.
+
+Use the `ask_user_question` tool to confirm. Question: "Slice [N/M]: [slice name] — [files affected]. [1-line summary]. Approve?". Header: "Slice [N]". Options: "Approve (Recommended)" (Lock this slice, write to artifact, proceed to slice [N+1]); "Revise this slice" (Adjust code before proceeding — describe what to change); "Rethink remaining slices" (This slice reveals a design issue — revisit decomposition).
+
+**Checkpoint cadence**: Slices 1-2: always individual. Slices 3+: individual if (a) mid-generation agent spawn was needed, (b) MODIFY touches an undiscussed file, or (c) self-verify fixed a violation.
+Otherwise batch 2-3 slices (max 3).
+
+### 7d. Incorporate feedback
+
+**Approve**: Lock this slice's code and **Edit the artifact immediately**:
+1. For each file in this slice, Edit the skeleton artifact to replace the empty code fence under that file's Architecture heading with the full generated code from 7a
+2. If a later slice contributes to a file already filled by an earlier slice: **rewrite the entire code fence** with the merged result (do not append alongside existing code)
+3. After merge, verify: no duplicate function definitions, imports deduplicated, exports list complete
+4. Update the Design History section: `- Slice N: [name] — approved as generated`
+- Proceed to next slice
+
+**Revise**: Update code per developer feedback. Re-run self-verify (7b). Re-present the same slice (7c). The artifact is NOT touched — only "Approve" writes to the artifact.
+
+**Rethink**: Developer spotted a design issue. If a previously approved slice is affected, flag the conflict and offer cascade revision — developer decides whether to reopen (if yes, Edit artifact entry).
+Update decomposition (add/remove/reorder remaining slices) and confirm before continuing.
+
+## Step 8: Integration Verification
+
+After all slices are complete, review cross-slice consistency:
+
+1. **Present integration summary** (under 15 lines):
+   ```
+   Integration: [feature name] — [N] slices complete
+
+   Slices: [brief list of slice names and file counts]
+   Cross-slice: [types consistent / imports valid / wiring complete]
+   Research constraints: [all satisfied / N violations noted]
+   ```
+
+2. **Verify research constraints**: Check each Precedent & Lesson and Verification Note from the research artifact against the generated code. List satisfaction status.
+
+3. **Confirm using the `ask_user_question` tool**. Question: "[N] slices complete, [M] files total. Cross-slice consistency verified. Proceed to design artifact?". Header: "Verify". Options: "Proceed (Recommended)" (Finalize the design artifact (verify completeness, update status)); "Revisit slice" (Reopen a specific slice for revision — Edit the artifact after); "Add missing" (A file or integration point is missing — add to artifact).
+
+## Step 9: Finalize Design Artifact
+
+The artifact was created as a skeleton in Step 6 and filled progressively in Step 7d. This step verifies completeness and finalizes.
+
+1. **Verify all Architecture entries are filled**: Every file heading from the decomposition must have a non-empty code block. If any are still empty (e.g., a slice was skipped), generate and fill them now.
+
+2. **Verify cross-slice file merges**: For files touched by multiple slices, confirm the Architecture entry contains the final merged code, not just the last slice's contribution.
+
+3. **Update frontmatter** via Edit:
+   - Set `status: complete`
+   - Update `last_updated` to current date
+   - Update `last_updated_by` to the User from the injected git context (fallback: "unknown")
+
+4. **Verify template completeness**: Ensure all 17 sections from the template reference in Step 6 are present and filled. Edit to fix any gaps.
+
+5. **Architecture format reminder**:
+   - **NEW files**: `### path/to/file.ext — NEW` + one-line purpose + full implementation code block
+   - **MODIFY files**: `### path/to/file.ext:line-range — MODIFY` + code block with only the modified/added code (no "Current" block — the original is on disk, implement reads it)
+
+## Step 10: Review & Iterate
+
+1. **Present the design artifact location**:
+   ```
+   Design artifact written to:
+   `thoughts/shared/designs/[filename].md`
+
+   [N] architectural decisions fixed, [M] new files designed, [K] existing files modified.
+   [S] slices generated, [R] revisions during generation.
+
+   Please review and let me know:
+   - Are the architectural decisions correct?
+   - Does the code match what you envision?
+   - Any missing integration points or edge cases?
+
+   When ready, run `/skill:plan thoughts/shared/designs/[filename].md` to sequence into phases.
+   ```
+
+2. **Handle follow-up changes**:
+   - Use the Edit tool to update the design artifact in-place
+   - Update frontmatter: `last_updated` and `last_updated_by`
+   - Add `last_updated_note: "Updated [brief description]"` to frontmatter
+   - If the change affects decisions, update both the Decisions section AND the Architecture code
+   - If new ambiguities arise, return to Step 5 (developer checkpoint)
+
+## Guidelines
+
+1. **Be Architectural**: Design shapes code; plans sequence work. Every decision must be grounded in `file:line` evidence from the actual codebase.
+
+2. **Be Interactive**: Don't produce the full design in one shot. Resolve ambiguities through the checkpoint first, get buy-in on the approach, THEN decompose and generate slice-by-slice.
+
+3. **Be Complete**: Code in the Architecture section must be copy-pasteable by implement. No pseudocode, no TODOs, no "implement here" placeholders. If you can't write complete code, an ambiguity wasn't resolved.
+
+4. **Be Skeptical**: Question vague requirements. If an existing pattern doesn't fit the new feature, say so and propose alternatives. Don't force a pattern where it doesn't belong.
+
+5. **Resolve Everything**: No unresolved questions in the final artifact. If something is ambiguous, ask during the checkpoint or micro-checkpoint. The design must be complete enough that plan can mechanically decompose it into phases.
+
+6. **Present Condensed, Persist Complete**: Micro-checkpoints show the developer summaries, signatures, and key code blocks. The artifact always contains full copy-pasteable code. If the developer asks to see full code, show it — but never default to walls of code in checkpoints.
+
+## Agent Usage
+
+| Context | Agents Spawned |
+|---|---|
+| Default (research artifact provided) | codebase-pattern-finder, codebase-analyzer, integration-scanner, precedent-locator |
+| Novel work (new library/pattern) | + web-search-researcher |
+| During code writing (if needed) | targeted codebase-analyzer for specific files |
+
+Spawn multiple agents in parallel when they're searching for different things. Each agent runs in isolation — provide complete context in the prompt, including specific directory paths when the feature targets a known module. Don't write detailed prompts about HOW to search — just tell it what you're looking for and where.
+
+## Important Notes
+
+- **Always chained**: This skill requires a research artifact produced by the research skill. There is no standalone design mode.
+- **File reading**: Always read research artifacts and referenced files FULLY (no limit/offset) before spawning agents
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read input files first (Step 1) before spawning agents (Step 2)
+  - ALWAYS wait for all agents to complete before identifying ambiguities (Step 3)
+  - ALWAYS resolve all ambiguities (Step 5) before decomposing into slices (Step 6)
+  - ALWAYS complete holistic decomposition before generating any slice code (Step 7)
+  - ALWAYS create the skeleton artifact immediately after decomposition approval (Step 6)
+  - NEVER leave Architecture code fences empty after their slice is approved — fill via Edit in Step 7d
+- NEVER skip the developer checkpoint — developer input on architectural decisions is the highest-value signal in the design process
+- NEVER edit source files — all code goes into the design document, not the codebase. This skill produces a document, not implementation. Source file editing is implement's job.
+- **Code is source of truth** — if the Architecture code section conflicts with the Decisions prose, the code wins. Update the prose.
+- **Checkpoint recordings**: Record micro-checkpoint interactions in Developer Context with `file:line` references, same as Step 5 questions.
+- **Frontmatter consistency**: Always include frontmatter, use snake_case for multi-word fields, keep tags relevant
+- CC auto-loads CLAUDE.md files when agents read files in a directory — no need to scan for them explicitly
+
+## Common Design Patterns
+
+- **New Features**: types first → backend logic → API surface → UI last. Research existing patterns first. Include tests alongside each implementation.
+- **Modifications**: Read current file FULLY. Show only the modified/added code scoped to changed sections. Check integration points for side effects.
+- **Database Changes**: schema/migration → store/repository → business logic → API → client. Include rollback strategy.
+- **Refactoring**: Document current behavior first. Plan incremental backwards-compatible changes. Verify existing behavior preserved.
+- **Novel Work**: Include approach comparison in Decisions. Ground in codebase evidence OR web research. Get explicit developer sign-off BEFORE writing code.