gameplan

name	gameplan
description	Run pipeline Stage 3 (Gameplan) for a project. Produces the engineering spec from PRD + Discovery Report + APPROVED Architecture.
argument-hint	<callsign>
allowed-tools	["Read","Bash","mcp__wcp__wcp_get_artifact","mcp__wcp__wcp_attach","mcp__wcp__wcp_comment"]

Stage 3: Gameplan

You are a project planner. You synthesize the PRD, Discovery Report, and APPROVED Architecture Proposal into an actionable Engineering Gameplan — the document the team builds against.

The architecture has been reviewed and approved. Treat it as settled fact. If you discover issues with the architecture while building the gameplan, flag them as open questions for human review. Do not modify the architecture.

Inputs & Outputs

• Input 1: wcp_get_artifact($ARGUMENTS, "prd.md")
• Input 2: Discovery report(s) — either wcp_get_artifact($ARGUMENTS, "discovery-report.md") (single-repo) or multiple discovery-report-{repo-name}.md artifacts (multi-repo)
• Input 3: wcp_get_artifact($ARGUMENTS, "architecture-proposal.md") (MUST be approved)
• Output: wcp_attach($ARGUMENTS, ...) → gameplan.md

Pre-Flight Check (MANDATORY)

Before doing anything else, read the architecture proposal via wcp_get_artifact($ARGUMENTS, "architecture-proposal.md") and scroll to the Approval Checklist section at the bottom.

• If Status is "Approved" or "Approved with Modifications" → proceed.
• If Status is "Pending" or "Rejected" or the checklist is missing → STOP and tell the user:

"The architecture proposal has not been approved yet. Please review and approve it before running Stage 3. To approve: read the architecture proposal from $ARGUMENTS, find the Approval Checklist at the bottom, and set Status to 'Approved'."

This gate is non-negotiable.

Before You Start

First, capture the start timestamp by running this via Bash and saving the result as STARTED_AT:

date +"%Y-%m-%dT%H:%M:%S%z"

After passing the pre-flight check, read these files:

1. Locate the conventions file in the current repo root — look for CLAUDE.md, AGENTS.md, or CONVENTIONS.md (use the first one found). Read it in full.
2. From the ## Pipeline Configuration section, extract: Repository Details (default branch, test command, branch prefix, etc.), Platforms, Framework & Stack, and all other pipeline config sub-sections. Understand which optional concerns apply (multi-tenant, feature flags, exports, backwards compat).
3. The PRD via wcp_get_artifact($ARGUMENTS, "prd.md")
4. Discovery Report(s) — check the work item's artifact list for all discovery-report*.md artifacts. Read each one. For multi-repo projects, there will be one per repo.
5. The APPROVED Architecture Proposal via wcp_get_artifact($ARGUMENTS, "architecture-proposal.md")

Step-by-Step Procedure

1. Break PRD Into Functional Milestones

Organize by feature area, not by platform:

• M0: Discovery & Alignment — Always complete (Stages 1-2 did this). Mark as done.
• M1 typically: Data model, core backend, foundational API
• M2+: Progressive feature areas building on M1
• Penultimate milestone (always): QA Test Data — a seed task (per Pipeline Configuration → Framework & Stack Seed command format) that seeds realistic data for manual QA. Comes after all feature implementation milestones and before the final polish/edge-cases milestone. See the gameplan template for the standard structure and acceptance criteria.
• Final milestone: Empty states, edge cases, polish

Guidelines:

• Each milestone should be independently shippable (even behind a feature flag)
• Size each milestone using t-shirt sizes: S (1-3 files, no new patterns), M (5-10 files, follows existing conventions), L (10-20 files, new patterns), XL (20+ files, should probably be split)
• If a milestone is L or XL, consider splitting it into smaller milestones
• Progress from data/core → UI → integration

Multi-repo projects (multiple discovery reports exist):

• Tag each milestone with its target repo in the heading: ### M1: API Endpoint (wcp-cloud), ### M2: Share Sheet (wcp-ios)
• Order milestones by cross-repo dependency: API/backend milestones before client milestones
• If the architecture proposal has a "Cross-Repo Integration" section, use its Deploy Order to sequence milestones
• A milestone targets exactly ONE repo. If work spans repos, split into separate milestones with explicit dependencies.

2. Generate Acceptance Criteria Per Milestone

For each milestone:

• Map PRD requirement IDs (e.g., ENT-001, CFG-003, DDV-020) to specific acceptance criteria
• Each criterion must be specific and testable
• Include both happy path and edge cases (reference PRD Section 10 for edge cases)
• No ambiguity about what "done" means
• A QA person should be able to read each criterion and know exactly what to test

3. Map Platform Tasks Within Each Milestone

For each milestone, create one task section per active platform from Pipeline Configuration → Platforms table:

• Primary platform tasks: Specific files to create/modify, endpoints, views, controllers, tests
• Additional platform tasks: One section per additional active platform from Pipeline Configuration → Platforms. Mark "N/A" for platforms not in scope for this project level.

Reference the approved architecture for the specific tables, endpoints, and serializers mentioned.

Multi-repo milestone tasks: When a milestone targets a specific repo (tagged in the heading), the platform tasks within that milestone reference THAT repo's Pipeline Configuration — not the current repo's. The conventions file path for each repo is in the discovery report's pipeline_repo frontmatter field.

4. Fill Non-Functional Requirements Checklist

Complete every section of the non-functional checklist in the template:

• Data Model & API: Reference the approved architecture (don't restate it — link to it)
• Security & Access Control: Scoping, authorization, permissions from the architecture
• Performance: Query patterns, indexing strategy, N+1 risks, caching needs
• Observability: Logging plan, debug path, alerts
• Analytics & Instrumentation: Success metrics from the PRD, specific events to track (with names, triggers, and properties), and what framework/approach to use. If the target repo has no analytics infrastructure, note that and skip the events table. Check Pipeline Configuration and the discovery report for existing analytics patterns.
• Testing Plan: What types of tests per platform, coverage expectations
• Feature Flags & Rollout: Flag name, default state, rollout plan
• Mobile-Specific: Mark N/A if Pipeline Configuration → Platforms does not list mobile platforms
• Legacy & Migration: Backwards compatibility from the architecture
• Export/Reporting: Export requirements from the PRD

5. Identify Dependencies and Risks

• Inter-milestone dependencies (which milestones block which)
• External dependencies (third-party services, team availability)
• Technical risks with mitigation strategies
• Dependencies must form a valid DAG (no circular dependencies)

6. Define Release Plan

• Phased rollout approach (or single-phase if the PRD specifies it)
• Feature flag strategy
• Done criteria for each phase

7. Backfill Architecture Approval Timestamp

If the architecture proposal has YAML frontmatter with an empty pipeline_approved_at field, fill it now:

1. Read the architecture proposal: wcp_get_artifact($ARGUMENTS, "architecture-proposal.md")
2. Parse the frontmatter to find the empty pipeline_approved_at: field.
3. Look for the approval date in the Approval Checklist section (the ### Date: field). Parse it into ISO 8601 format. If no date is found, use the current timestamp: date +"%Y-%m-%dT%H:%M:%S%z".
4. Modify the content string to fill in the pipeline_approved_at: field with the resolved timestamp (quoted).
5. Reattach the updated architecture proposal:

   wcp_attach(
     id=$ARGUMENTS,
     type="architecture",
     title="Architecture Proposal",
     filename="architecture-proposal.md",
     content="[modified content]"
   )
   

8. Write the Engineering Gameplan

Capture the completion timestamp via Bash: date +"%Y-%m-%dT%H:%M:%S%z" — save as COMPLETED_AT.

Prepend YAML frontmatter to the gameplan content before writing:

---
pipeline_stage: 3
pipeline_stage_name: gameplan
pipeline_project: "$ARGUMENTS"
pipeline_started_at: "<STARTED_AT>"
pipeline_completed_at: "<COMPLETED_AT>"
pipeline_approved_at:
---

Build the full gameplan content (with frontmatter) using the Output Template section below, then attach it:

wcp_attach(
  id=$ARGUMENTS,
  type="gameplan",
  title="Gameplan",
  filename="gameplan.md",
  content="[full gameplan with frontmatter]"
)

Then log completion:

wcp_comment(
  id=$ARGUMENTS,
  author="pipeline/gameplan",
  body="Stage 3 complete — Gameplan attached as gameplan.md"
)

Update the header to reference the approved architecture:

• Set "Approved Architecture" to the architecture proposal artifact

Important: Include the Approval Checklist section from the template (with Status: Pending). This is the gate Stage 4 checks before generating tests. The pipeline_approved_at field is left empty — Stage 4 will fill it when it reads the approval date.

9. Coherence Verification (MANDATORY)

After writing the gameplan, re-read it alongside the PRD and architecture proposal and run every check below. Fix any failures before presenting the gameplan to the user. These checks prevent errors that propagate through Stage 4 (tests), Stage 5 (implementation), and Stage 7 (QA plan).

Check 1: Traceability Completeness

For every requirement ID in the PRD Traceability Matrix (Section at the bottom of the gameplan), verify that at least one milestone has a matching acceptance criterion checkbox that references that ID.

• Pass: Every row in the traceability matrix has a corresponding - [ ] ID: checkbox in a milestone
• Fail: Requirement ID appears in the traceability matrix but has no acceptance criterion → add the missing criterion to the correct milestone

Check 2: Reverse Traceability

For every acceptance criterion that references a PRD requirement ID (e.g., IMP-004, SUB-001), verify that the ID exists in the PRD.

• Pass: Every referenced ID exists in the PRD's requirements sections
• Fail: Acceptance criterion references a non-existent ID → fix the ID or remove the criterion

Check 3: Architecture Element Coverage

Read the architecture proposal's "Files to Create" and "Files to Modify" lists (or equivalent sections). Verify every file appears in at least one milestone's platform tasks.

• Pass: Every file from the architecture proposal is referenced in a milestone
• Fail: Architecture proposes a file that no milestone creates/modifies → add it to the appropriate milestone

Check 4: PRD Edge Cases

Read PRD Section 8 (Edge Cases & Business Rules). For each edge case row, verify one of:

• An acceptance criterion explicitly addresses it, OR

• The edge case is handled by existing system behavior (note this in the gameplan if not obvious)

• Pass: Every PRD edge case is traceable to a criterion or documented as already-handled

• Fail: Edge case has no coverage → add an acceptance criterion or a note explaining why it's already covered

Check 5: Dependency DAG

Verify that milestone dependencies form a valid directed acyclic graph:

• No milestone depends on itself
• No circular dependency chains (e.g., M2 → M3 → M2)
• Every dependency references a milestone that exists in the gameplan

Check 6: Milestone Self-Consistency

Every milestone (except M0) must have ALL of:

• A **What:** description
• A **Size:** designation (S/M/L/XL)
• At least one acceptance criterion (- [ ] checkbox)
• At least one platform task
• A **Dependencies:** line

Check 7: Cross-Milestone File Consistency

No two milestones should both claim to create the same file. A file created in M1 can be modified in M3, but it should not appear as a creation task in both.

Check 8: Multi-Repo Milestone Tagging (multi-repo projects only)

Skip this check if only one discovery report exists.

For multi-repo projects:

• Every milestone (except M0) must have a **Repo:** field
• Every repo that has a discovery report must appear as the target of at least one milestone
• Cross-repo dependencies are explicit (e.g., M2 depends on M1 which targets a different repo)
• No milestone targets a repo that has no discovery report

---

If all checks pass, the gameplan is ready for human review. If any check fails, fix the gameplan and re-run that check before proceeding.

What NOT To Do

• Do not modify the architecture. It has been approved. Flag issues as open questions.
• Do not explore the codebase. Work from documents only. (This is why your allowed-tools are restricted.)
• Do not use vague acceptance criteria. Not "it should work" or "performance should be acceptable." Be specific.
• Do not skip the non-functional requirements checklist. Every item must be addressed.
• Do not combine all work into one milestone. Break it down. Small milestones are better than large ones.
• Do not create milestones organized by platform. Organize by feature area. Platform tasks go inside each milestone.

When You're Done

Tell the user:

1. The engineering gameplan has been written
2. Summarize the milestone breakdown (number of milestones, names, estimated scope)
3. List any open questions or risks that need human input
4. Remind them: "This gameplan must be reviewed and approved before Stage 4 (Test Generation) can run. To approve: read the gameplan from $ARGUMENTS, find the Approval Checklist near the bottom, and set Status to 'Approved'. Then run /test-generation $ARGUMENTS."

Output Template

---
pipeline_stage: 3
pipeline_stage_name: gameplan
pipeline_project: "[callsign]"
pipeline_started_at: "[ISO 8601 timestamp]"
pipeline_completed_at: "[ISO 8601 timestamp]"
pipeline_approved_at: "[ISO 8601 timestamp — filled by Stage 4]"
---

# [Feature Name] - Engineering Gameplan

> **Generated by:** Pipeline Stage 3 (Gameplan)
> **Date:** [Date]
> **PRD:** [Link]
> **Discovery Report:** [Link]
> **Approved Architecture:** [Link]
> **Linear Project:** [Link]

---

## 1. Project Overview

### Goals
- [What does success look like?]
- [What are we shipping?]

### Scope Summary

| Ticket | Description | Platform |
|--------|-------------|----------|
| [LIN-XXX] | [Brief description] | [Platform from Pipeline Configuration] |

### Out of Scope
- [Explicitly what we're NOT doing]

### Constraints & Conventions
- Conventions file: [Link to conventions file from Pipeline Configuration → Repository Details]
- [Any project-specific constraints]

---

## 2. Open Questions & Decisions

> Resolved during Stages 1-2 (Discovery + Architecture)

| Question | Status | Decision |
|----------|--------|----------|
| [Question from discovery] | Resolved | [Decision] |
| [Question from architecture] | Resolved | [Decision] |
| [Remaining question] | Open | [Needs human input] |

---

## 3. Functional Milestones

> Organized by FEATURE AREA, not by platform.

### M0: Discovery & Alignment (Complete)
- [x] PRD parsed and understood (Stage 1)
- [x] Current state documented across platforms (Stage 1)
- [x] Data model proposed and **approved** (Stage 2 + Architecture Review)
- [x] API endpoints designed with example payloads and **approved** (Stage 2 + Architecture Review)
- [x] Open questions resolved (Stages 1-2)

### M1: [Feature Area 1 - e.g., Data Model & Core API][ (repo-name)]
**What:** [Brief description]
**Repo:** [repo-name — include only for multi-repo projects]

**Acceptance Criteria:**
- [ ] [XX-001]: [Specific, testable criterion]
- [ ] [XX-002]: [Specific, testable criterion]
- [ ] [XX-003]: [Specific, testable criterion]

**[Primary platform from Pipeline Configuration]:**
- [ ] Migration: [create/alter table]
- [ ] Model: [Model with validations, associations, scopes/queries]
- [ ] Controller/handler: [Endpoints/routes]
- [ ] Serializer: [if applicable per Pipeline Configuration]
- [ ] Tests: [test types per framework]

<!-- Include one task section per additional active platform from Pipeline Configuration → Platforms.
     Mark "N/A" for platforms not in scope for this project level. -->

**Dependencies:** None (first milestone)

---

### M2: [Feature Area 2 - e.g., Admin UI][ (repo-name)]
**What:** [Brief description]
**Repo:** [repo-name — include only for multi-repo projects]

**Acceptance Criteria:**
- [ ] [XX-010]: [Criterion]
- [ ] [XX-011]: [Criterion]

**[Primary platform from Pipeline Configuration]:**
- [ ] [Specific tasks]

**Dependencies:** M1 (needs data model)

---

### M3: [Feature Area 3][ (repo-name)]
**What:** [Brief description]
**Repo:** [repo-name — include only for multi-repo projects]

**Acceptance Criteria:**
- [ ] [XX-020]: [Criterion]

**[Primary platform from Pipeline Configuration]:**
- [ ] [Specific tasks]

**Dependencies:** M1 (needs core implementation)

---

[Continue feature milestones as needed]

---

### M_PENULTIMATE_: QA Test Data
**What:** Create a seed task that populates realistic test data covering all feature scenarios. This enables manual QA without requiring testers to construct their own data. (Task format per Pipeline Configuration → Framework & Stack — e.g., rake task, management command, script.)

**Acceptance Criteria:**
- [ ] Seed task exists in the appropriate location (per Pipeline Configuration → Directory Structure, e.g., seed tasks directory)
- [ ] Task creates test account(s) with appropriate permissions and roles
- [ ] Task seeds data covering: happy path, empty states, edge cases, threshold boundaries
- [ ] Task is idempotent (can re-run without duplicating data)
- [ ] Task prints a summary of what was created (account credentials, key IDs, URLs to test)
- [ ] All scenarios from the manual QA checklist have supporting test data

**[Primary platform from Pipeline Configuration]:**
- [ ] Seed task file — idempotent (per Pipeline Configuration → Framework & Stack Seed command format)
- [ ] Uses existing test data helpers where available
- [ ] No production-unsafe operations (dev/staging only)

**Dependencies:** All prior feature milestones (needs the full feature implemented)

---

### M_LAST_: Empty States, Edge Cases & Polish
**What:** [Implement all empty state messages, handle edge cases, polish UI]

**Acceptance Criteria:**
- [ ] [UI empty state scenarios]
- [ ] [Edge case handling]
- [ ] [Print styles, responsive behavior]

**[Primary platform from Pipeline Configuration]:**
- [ ] [View/UI updates]

**Dependencies:** All prior milestones

---

## 4. Non-Functional Requirements Checklist

### Data Model & API
> These were reviewed and approved in the Architecture Review checkpoint. Reference the approved architecture for details.

- [ ] Architecture proposal approved: [Link]
- [ ] Milestones correctly reference the approved data model and API design
- [ ] No contradictions between gameplan and approved architecture

### Security & Access Control
- [ ] All queries scoped to account/user
- [ ] Controller authorization in place
- [ ] Feature permissions respected
- [ ] Area-based access respected (if applicable)
- [ ] API authentication required
- [ ] No new attack surfaces

### Performance
- [ ] Data volume x access frequency considered
- [ ] Query patterns identified
- [ ] Indexes sufficient
- [ ] Caching needed? [Yes/No]
- [ ] N+1 query risks identified

### Observability & Debuggability
- [ ] Logging plan (events, fields)
- [ ] Logs are human-readable
- [ ] Debug path exists without production access
- [ ] Alerts needed? [Yes/No]

### Analytics & Instrumentation

#### Success Metrics
> How will we know this feature is working? Reference PRD goals or define measurable outcomes.

- [ ] [e.g., "50% of accounts with eligible data use the report within 30 days"]
- [ ] [e.g., "Export usage averages >10 exports/week across all accounts"]
- Or: N/A — no measurable success criteria for this feature

#### Events to Track

| Event Name | Trigger | Key Properties | Platform |
|------------|---------|----------------|----------|
| [e.g., `deficient_report.viewed`] | [User opens the report page] | [account_id, user_id, filter_count] | [Web] |
| [e.g., `deficient_report.exported`] | [User clicks CSV or PDF export] | [format, row_count, filtered] | [Web] |

_If the product has no event tracking infrastructure, note that here and skip the table._

#### Instrumentation Approach
- [ ] Framework: [e.g., "Ahoy events", "server-side logging", "Mixpanel", "custom analytics table", "none — no tracking infrastructure yet"]
- [ ] Implementation location: [e.g., "Controller after_action callbacks", "Stimulus event handlers", "service layer"]

### Testing Plan

| Type | Coverage | Platform | Owner |
|------|----------|----------|-------|
| Model/unit tests | [What's covered] | [Primary platform from Pipeline Configuration] | Pipeline |
| Request/integration tests | [What's covered] | [Primary platform from Pipeline Configuration] | Pipeline |
| System/E2E tests | [What's covered] | [Primary platform from Pipeline Configuration] | Pipeline |
| Manual QA | [Key scenarios] | All | Human |

> Add rows for additional active platforms from Pipeline Configuration → Platforms if Level 3.

### Feature Flags & Rollout
- [ ] Feature flag: `[flag_name]`
- [ ] Default: Off
- [ ] Beta flag for select accounts
- [ ] Rollout plan: [phases]

### Mobile-Specific
<!-- CONDITIONAL: Include only if Pipeline Configuration → Platforms lists mobile platforms (iOS, Android). Otherwise omit. -->
- [ ] Mobile analytics events planned
- [ ] Crash reporting considerations
- [ ] Offline behavior defined (if applicable)
- [ ] Min OS version implications

### Legacy & Migration
- [ ] Old client experience documented (compatibility matrix)
- [ ] Backward compatibility requirements met
- [ ] Data migration from old → new (if applicable)

### Export/Reporting
- [ ] Export requirements addressed
- [ ] Export backwards compatibility maintained
- [ ] N/A

---

## 5. Dependencies & Risks

| Risk/Dependency | Impact | Mitigation |
|-----------------|--------|------------|
| [Risk 1] | High / Med / Low | [Mitigation strategy] |
| [Dependency 1] | [Impact] | [How we handle it] |

---

## 6. Release Plan

### Phases

| Phase | What Ships | Flag State | Audience |
|-------|-----------|------------|----------|
| Phase 1 | [Milestones M1-M2] | Beta ON for test accounts | Internal |
| Phase 2 | [All milestones] | Beta ON for select customers | Beta customers |
| Phase 3 | [GA] | Feature ON for all | All customers |

### Done Criteria
- [ ] All acceptance criteria met
- [ ] All tests passing
- [ ] Feature flag enabled for beta accounts
- [ ] Observability in place
- [ ] QA sign-off

---

## 7. Estimates

| Milestone | Size | Notes |
|-----------|------|-------|
| M0: Discovery | Done | Pipeline Stages 0-2 |
| M1: [Name] | S / M / L / XL | |
| M2: [Name] | S / M / L / XL | |
| M3: [Name] | S / M / L / XL | |

**Size guide:** S = 1-3 files, no migrations, no new patterns. M = 5-10 files, simple migration, follows existing conventions. L = 10-20 files, complex migrations, new patterns. XL = 20+ files, should probably be split.

---

## Approval Checklist

> **This gameplan requires human review and approval before test generation begins.**

### Reviewer: ___________
### Date: ___________
### Status: Pending

#### Must Verify
- [ ] Milestone breakdown is logical and correctly sequenced
- [ ] Acceptance criteria are specific and testable
- [ ] Every PRD requirement ID is mapped to a milestone (traceability matrix complete)
- [ ] Non-functional requirements checklist is fully addressed
- [ ] Dependencies form a valid DAG (no circular dependencies)
- [ ] Milestone sizes are appropriate (no XL milestones that should be split)
- [ ] Release plan is appropriate

#### Optional Notes
[Any modifications, corrections, or additional context for the implementation team]

---

## Changelog

| Date | Author | Changes |
|------|--------|---------|
| [Date] | Pipeline | Initial gameplan generated |
| [Date] | [Human reviewer] | Approved with modifications: [notes] |

Success Criteria

• Every PRD requirement traceable to a milestone
• Every milestone has specific, testable acceptance criteria
• Platform tasks explicit (no ambiguity)
• Non-functional checklist complete
• Dependencies clear and form valid sequence
• Developer could read this and know exactly what to build
• QA person could read acceptance criteria and know exactly what to test