SNIPER

Appearance

/sniper-solve -- Phase 3: Epic Sharding & Story Creation (Single Agent) ​

You are executing the /sniper-solve command. Your job is to break the PRD into implementable epics and self-contained stories. This phase runs as a single agent -- you do the work directly, no team is spawned. Follow every step below precisely.

Arguments: $ARGUMENTS

Step 0: Pre-Flight Checks ​

Perform ALL checks before proceeding. If any critical check fails, STOP.

0a. Verify SNIPER Is Initialized ​

  1. Read .sniper/config.yaml.
  2. If the file does not exist or project.name is empty:
    • STOP. Print: "SNIPER is not initialized. Run /sniper-init first."

0b. Verify Phase 2 Artifacts Exist ​

Check that the following files exist and are non-empty. Read each file to verify it has substantive content (not just a template with empty sections).

  1. docs/prd.md -- REQUIRED. If missing or empty, STOP and print: "Phase 2 artifact docs/prd.md is missing. Run /sniper-plan first."
  2. docs/architecture.md -- REQUIRED. If missing or empty, STOP and print: "Phase 2 artifact docs/architecture.md is missing. Run /sniper-plan first."
  3. docs/ux-spec.md -- REQUIRED. If missing or empty, STOP and print: "Phase 2 artifact docs/ux-spec.md is missing. Run /sniper-plan first."
  4. docs/security.md -- Recommended. If missing, print a warning but continue.

0c. Verify Phase 2 Was Approved ​

  1. Read state.phase_history from config.yaml.
  2. Find the entry with phase: plan.
  3. Check that approved_by is not null and not "rejected".
  4. If plan was not approved: Print a warning:

    "WARNING: Phase 2 (plan) has not been formally approved. The planning review gate is strict -- artifacts should be reviewed and approved before sharding into stories. Continue anyway? (yes/no)"

    • If no, STOP.
    • If yes, proceed with a note in the output.

0d. Config Migration Check ​

  1. Read schema_version from .sniper/config.yaml.
  2. If schema_version is absent or less than 2, run the v1→v2 migration. Write the updated config before proceeding.

0e. Verify Phase State ​

  1. Determine the current active phase from state.phase_log.
  2. If no active phase: Good -- proceed.
  3. If active phase is solve: Already in progress.
    • Ask the user: "A solve phase is already in progress ({context}). Options: (a) Resume it (b) Start a new solve with a different context"
  4. If active phase is something else:
    • Ask the user: "You have an active {phase} phase ({context}). Options: (a) Pause it and start solving (b) Complete {phase} first"

0f. Amendment Detection for Stories ​

  1. Check if docs/epics/ and docs/stories/ directories exist and contain files.
  2. If story files exist:
    • Scan each story file for a > **Status:** Complete (Sprint {N}) marker.
    • Completed stories are NEVER overwritten. They are preserved as-is.
    • Draft stories (no completion marker) can be amended: updated acceptance criteria, refreshed embedded context.
    • New requirements (from amended PRD) generate new stories with the next available story number.
    • Removed requirements — stories for removed PRD items are marked > **Status:** Deprecated rather than deleted.
  3. If no story files exist: Normal create mode.

Step 1: Update Lifecycle State ​

Edit .sniper/config.yaml:

  1. Append to state.phase_log:
    yaml
    - phase: solve
  context: "{from --context argument, or 'initial' for first run, or 'iteration-N' for re-runs}"
  started_at: "{current ISO timestamp}"
  completed_at: null
  approved_by: null

Step 2: Load Persona and Context ​

This phase does NOT spawn a team. Instead, adopt the scrum-master persona yourself.

  1. Read .sniper/personas/process/scrum-master.md -- internalize this role. You ARE the scrum master for this step.
  2. Read .sniper/personas/cognitive/systems-thinker.md -- apply this thinking pattern to your sharding decisions.
  3. If domain_pack is set in config.yaml, read domain context files from .sniper/domain-packs/{domain_pack}/context/.

Step 3: Read All Phase 2 Artifacts ​

Read each artifact fully. You will need deep understanding of all of these to shard properly.

  1. Read docs/prd.md -- This is your primary input. Pay close attention to:

    • P0 requirements (must-have for v1)
    • P1 requirements (should-have)
    • P2 requirements (nice-to-have, likely deferred)
    • User stories and acceptance criteria
    • Non-functional requirements
    • Out-of-scope items

  2. Read docs/architecture.md -- Pay close attention to:

    • Component boundaries (these inform epic boundaries)
    • Data models (stories need embedded schema context)
    • API contracts (stories need embedded endpoint specs)
    • Infrastructure requirements
    • Cross-cutting concerns (auth, logging, etc.)

  3. Read docs/ux-spec.md -- Pay close attention to:

    • Screen inventory (each screen may map to one or more stories)
    • User flows (flows cross multiple components)
    • Component hierarchy (informs frontend story scope)
    • Responsive breakpoints and states

  4. Read docs/security.md (if exists) -- Pay close attention to:

    • Auth model (will be its own epic or stories)
    • Encryption requirements
    • Compliance requirements

Step 4: Read Templates ​

  1. Read .sniper/templates/epic.md -- Every epic MUST follow this template structure.
  2. Read .sniper/templates/story.md -- Every story MUST follow this template structure.

Step 5: Create Output Directories ​

Create the following directories if they do not exist:

  • docs/epics/
  • docs/stories/

If the directories already exist and contain files from a previous run, note this. The files will be overwritten.

Step 6: Shard PRD into Epics ​

Break the PRD into 6-12 epics. Follow these rules strictly:

Sharding Rules ​

  1. No overlap: Every requirement from the PRD belongs to exactly ONE epic. No requirement should appear in two epics.
  2. Clear boundaries: Each epic has explicit "In Scope" and "Out of Scope" sections.
  3. Architecture alignment: Epic boundaries should align with architecture component boundaries where possible.
  4. Dependency DAG: Epic dependencies must form a Directed Acyclic Graph -- no circular dependencies.
  5. Sizing: Each epic should be roughly similar in size (not one massive epic and five tiny ones).
  6. Embedded context: Each epic must EMBED the relevant architecture sections, not just reference them.

Suggested Epic Structure ​

Consider organizing epics along these axes (adapt to the specific project):

  • E01: Foundation -- Project setup, configuration, infrastructure scaffolding
  • E02: Authentication & Authorization -- Auth flows, RBAC, session management
  • E03: Core Data Layer -- Database models, migrations, seed data, repositories
  • E04-E08: Feature Epics -- One epic per major feature area from the PRD
  • E09: API Layer -- API contracts, middleware, validation, error handling
  • E10: Frontend Shell -- Layout, navigation, routing, shared components
  • E11-E12: Integration -- Third-party integrations, background jobs, notifications

Adapt this structure to fit the actual project. Do NOT force-fit the project into this template if it does not make sense.

Writing Each Epic ​

For each epic, create a file at docs/epics/E{NN}-{slug}.md where:

  • {NN} is a zero-padded two-digit number (E01, E02, etc.)
  • {slug} is a kebab-case short name (e.g., auth-system, core-data, dashboard-ui)

Follow the template at .sniper/templates/epic.md exactly. Fill in:

  • Status: Draft
  • Priority: P0, P1, or P2 (based on the requirements it covers)
  • Estimated Points: Total story points for all stories in this epic
  • Dependencies: List other epics this depends on (e.g., "E01-foundation" if it needs project setup)
  • Scope: Clear in/out boundaries
  • Architecture Context: COPY the relevant sections from docs/architecture.md -- data models, API contracts, component descriptions. Do NOT just write "see architecture doc."
  • Stories table: List the stories that will be created in Step 7 (you can fill this in after Step 7)
  • Acceptance Criteria: Epic-level criteria -- what must be true when ALL stories in this epic are done
  • Technical Notes: Implementation-specific guidance

Step 7: Create Stories for Each Epic ​

For each epic, create 3-8 stories. Follow these rules strictly:

Story Rules ​

  1. Self-contained: A developer reading ONLY the story file must have ALL context needed to implement it. No "see PRD" or "see architecture doc" -- embed the context.
  2. Given/When/Then: All acceptance criteria MUST use Given/When/Then format.
  3. File ownership: Each story must declare which directories it touches (from the ownership rules in config.yaml).
  4. Complexity: Estimate S/M/L/XL. If any story is XL, split it into smaller stories.
  5. Dependencies: Declare inter-story dependencies. Must form a DAG.
  6. Test requirements: Specify what tests are needed (unit, integration, e2e).

Writing Each Story ​

For each story, create a file at docs/stories/S{NN}-{slug}.md where:

  • {NN} is a zero-padded two-digit number, globally sequential across all epics (S01, S02, ..., S42, etc.)
  • {slug} is a kebab-case short name

Follow the template at .sniper/templates/story.md exactly. Fill in:

  • Epic reference: Which epic this belongs to
  • Complexity: S, M, L (never XL -- split if needed)
  • Priority: P0, P1, or P2
  • File Ownership: Which directories from config.yaml this story touches (e.g., "backend, tests" or "frontend, tests")
  • Dependencies: Other story IDs that must complete first

Embedded Context (CRITICAL) ​

For the "Embedded Context" section, COPY the relevant content from the source documents:

  • From PRD: Copy the specific requirements and user stories this story implements. Include exact acceptance criteria text.
  • From Architecture: Copy relevant data models (with field types), API endpoint specs (with request/response shapes), and architectural patterns to follow.
  • From UX Spec: For frontend stories, copy the screen descriptions, component specs (with all states), user flow segments, and responsive requirements.

Do NOT summarize or paraphrase. COPY the exact sections. A developer should not need to open any other document.

Acceptance Criteria ​

Write testable assertions in Given/When/Then format:

1. **Given** a user is not authenticated
   **When** they access the dashboard endpoint
   **Then** they receive a 401 Unauthorized response with a redirect URL to the login page

2. **Given** a user is authenticated with role "admin"
   **When** they request the user list endpoint with pagination params page=2, limit=20
   **Then** they receive a 200 response with exactly 20 user objects and correct pagination metadata

Be specific. Include status codes, field names, exact behaviors.

Test Requirements ​

Specify what tests are needed:

- [ ] Unit tests: {specific functions/methods to test}
- [ ] Integration tests: {specific API endpoints or flows to test}
- [ ] E2E tests (if applicable): {specific user scenarios}

Step 8: Backfill Epic Story Tables ​

After creating all stories, go back to each epic file and update the Stories table with the actual story IDs, names, complexity, dependencies, and file ownership.

Step 9: Self-Review Against Checklist ​

Read .sniper/checklists/story-review.md and evaluate your work against every item.

Epic Structure Review ​

Go through each epic checklist item:

  • [ ] Epics number between 6-12
  • [ ] No overlap between epics
  • [ ] Epic dependencies form a DAG
  • [ ] Each epic has clear scope boundaries
  • [ ] Architecture context is EMBEDDED
  • [ ] Complexity estimates are realistic

Story Quality Review ​

For EACH story, verify:

  • [ ] Story is self-contained (a developer can implement from the story alone)
  • [ ] PRD context is EMBEDDED (not just referenced)
  • [ ] Architecture context is EMBEDDED
  • [ ] UX context is EMBEDDED for frontend stories
  • [ ] Acceptance criteria use Given/When/Then format
  • [ ] Every criterion is testable
  • [ ] Test requirements are specified
  • [ ] File ownership is assigned
  • [ ] Dependencies are declared
  • [ ] Complexity is S/M/L (not XL)

Coverage Review ​

  • [ ] All P0 requirements have implementing stories
  • [ ] All P1 requirements have implementing stories
  • [ ] All architecture components have at least one story
  • [ ] Story dependency chains allow reasonable sprint planning

Step 10: Fix Issues Found in Self-Review ​

If the self-review identified any issues:

  1. Fix each issue directly by editing the relevant epic or story file.
  2. Common fixes:
    • Missing embedded context: Go back to the source doc, copy the relevant section into the story.
    • Vague acceptance criteria: Rewrite with specific Given/When/Then and concrete values.
    • XL story: Split into two or more smaller stories with clear boundaries.
    • Missing test requirements: Add specific test types and what to test.
    • Circular dependencies: Restructure the dependency graph to break the cycle.
  3. After fixing, re-verify the specific items that failed.

Step 11: Update Lifecycle State ​

Edit .sniper/config.yaml:

  1. Update artifact tracking:
    • Set state.artifacts.epics.status: draft and increment state.artifacts.epics.version
    • Set state.artifacts.stories.status: draft and increment state.artifacts.stories.version
  2. Update the solve entry in state.phase_log:
    • Set completed_at: "{current ISO timestamp}"
    • Set approved_by: "auto-flexible" (this is a flexible gate)

Step 12: Present Results and Next Steps ​

Print a formatted summary:

============================================
  SNIPER Phase 3: Epic Sharding Complete
============================================

  Epics Created: {count}
  Stories Created: {count}

  Epic Summary:
    E01-{slug}  |  P{x}  |  {story count} stories  |  {total points} pts
    E02-{slug}  |  P{x}  |  {story count} stories  |  {total points} pts
    ...

  Story Breakdown by Complexity:
    Small (S):  {count}
    Medium (M): {count}
    Large (L):  {count}

  Story Breakdown by File Ownership:
    Backend:        {count} stories
    Frontend:       {count} stories
    Infrastructure: {count} stories
    Full-stack:     {count} stories

  Self-Review Results:
    Passed:    {count}/{total} checklist items
    Fixed:     {count} issues auto-corrected
    Attention: {count} items for async review

  Review Gate: FLEXIBLE (auto-advanced)

============================================
  Next Steps
============================================

  1. Review epics in `docs/epics/` and stories in `docs/stories/`
  2. When ready, run `/sniper-sprint` to begin Phase 4: Implementation Sprint
  3. `/sniper-sprint` will ask you to select which stories to include in the sprint
  4. Or run `/sniper-status` to see the full lifecycle state

  Recommended first sprint: Start with foundation stories (E01)
  and any stories with no dependencies.

============================================

  Files:
    Epics:   docs/epics/E01-*.md through docs/epics/E{NN}-*.md
    Stories: docs/stories/S01-*.md through docs/stories/S{NN}-*.md

============================================

Feature-Scoped Mode ​

If $ARGUMENTS contains --feature SNPR-{XXXX}:

  1. Skip Steps 0b and 0c (no need to check for main PRD or plan approval).
  2. Step 3: Instead of reading main PRD/architecture/UX-spec, read:
    • docs/features/SNPR-{XXXX}/spec.md (replaces PRD as primary input)
    • docs/features/SNPR-{XXXX}/arch-delta.md (replaces architecture for feature scope)
    • docs/architecture.md (for broader system context)
    • docs/conventions.md (if exists, for coding patterns)
  3. Step 5: Create stories in docs/features/SNPR-{XXXX}/stories/ instead of docs/stories/.
  4. Step 6: Skip epic creation. Feature stories don't need epics (the feature IS the epic).
  5. Step 7: Number stories as S01, S02, etc. within the feature directory. Target 3-8 stories.
  6. Step 7 context embedding: Embed context from the feature spec and arch-delta, NOT the main PRD.
  7. Step 11: Update state.features[].stories_total with the count.

IMPORTANT RULES ​

  • This phase runs as a SINGLE AGENT. Do NOT create a team or spawn teammates.
  • You ARE the scrum master. You do the work directly.
  • Stories MUST be self-contained. This is the most critical quality requirement. A developer reading only the story file must have all context to implement it.
  • EMBED context from PRD, architecture, and UX spec. Do NOT just reference them.
  • Acceptance criteria MUST be Given/When/Then format with specific, testable assertions.
  • No story should be XL complexity. Split large stories.
  • Epic and story dependencies MUST form a DAG. No circular dependencies.
  • If $ARGUMENTS contains "dry-run", perform Steps 0-4 only (read all artifacts and plan the sharding) and present the proposed epic structure without creating files. Let the user approve before proceeding.
  • If $ARGUMENTS contains a specific epic count (e.g., "8 epics"), use that as a target instead of the 6-12 range.
  • All file paths are relative to the project root.
  • Do NOT start implementation. Do NOT write code. This phase produces planning artifacts only.
  • Do NOT proceed to /sniper-sprint automatically -- let the user initiate it.