ComputerConnection/sprint-planner

Sprint Planner

A three-stage product strategy pipeline that produces a product audit, thesis-driven roadmap, and sprint plan with PM decision gates. Each stage builds on the previous one, and the quality of the output depends entirely on reading real source code — never planning from specs alone.

Why This Pipeline Exists

Most sprint plans fail because they start from a feature list, not from reality. A PM says "we need segments to be actionable" without knowing that the segment page is six read-only cards with no action handlers. An engineer estimates "2 days" for device tracking without knowing there's no devices table — just a service that reconstructs device identity from work order records on every query.

This pipeline fixes that by forcing three things:

1. Start from code. Read every route, component, type definition, and API endpoint. The power comes from catching things like "the customer picker is a UUID field" or "the board is a placeholder <div> with a comment saying the feature isn't built." You only find those by reading source.
2. Articulate a thesis before solutions. A roadmap that says "fix bugs, add features, improve performance" is useless. A roadmap that says "device history IS the relationship — everything flows from that insight" gives every sprint a north star.
3. PM gates prevent building the wrong thing confidently. The questions between phases force real business decisions before engineering begins. Bad PM questions: "should we use React?" Good PM questions: "When a customer's score drops, do we show them which component changed, or just the new total?"

The Pipeline

Stage 1: Product Audit    → {APP}_PRODUCT_AUDIT.md
Stage 2: Product Roadmap  → {APP}_ROADMAP.md
Stage 3: Sprint Plan      → {APP}_SPRINT_PLAN.md

Each stage can be run independently, but they're designed to flow together. If the user asks for just a sprint plan, check whether an audit and roadmap exist first — if not, suggest running the earlier stages.

---

Stage 1: Product Audit

The audit answers one question: what is this thing, actually? Not what the README says, not what the Jira board claims — what does the source code reveal about the product's true state?

How to Conduct the Audit

Step 1: Read the Source Code

This is non-negotiable. Read:

• Routes and pages — every page.tsx, route.ts, or equivalent. Map every screen the user can visit.
• Components — what UI elements exist? Are they real implementations or placeholder divs?
• Type definitions — domain types reveal the data model. Look for TODO comments, any types, commented-out fields.
• API endpoints — every route handler. What's the actual surface area?
• Server handlers and services — business logic lives here. Look for hardcoded values, missing validations, disconnected systems.

Build a mental model of: what screens exist, what data flows between them, what actions a user can take, and where the gaps are.

Step 2: Cross-Reference Git History

Use these specific commands to build a development activity picture:

# Per-directory commit count over 3 time windows
git log --oneline --since="2 weeks ago" -- <path> | wc -l
git log --oneline --since="1 month ago" -- <path> | wc -l
git log --oneline --since="3 months ago" -- <path> | wc -l

# Last meaningful commit per directory
git log -1 --format="%H %ad %s" -- <path>

# Active branches that touch this area
git branch -a --list "*feature*" --list "*feat*" | head -20

# Check PROGRESS.md or equivalent sprint tracker if it exists

Check three time windows: 2 weeks (active development), 1 month (recent work), 3 months (project history). The pattern that matters: an app with 50 commits in 3 months but 0 in 2 weeks tells a different story than one with steady 5/week.

What to look for:

• Development velocity — which files are actively being worked on vs. stale?
• Active vs. abandoned — a placeholder that was last touched 6 months ago is different from one committed last week.
• Patterns — are similar bugs being fixed repeatedly? Are there oscillating changes (feature added, then reverted, then re-added)?

A file with no commits in 6 months sitting next to actively developed files is a signal worth noting.

Step 3: Evaluate Every Surface

For each app, module, or feature area, assess:

1. Purpose clarity — Can you tell what this screen/feature is for within 3 seconds? If not, it's confused.
2. Workflow integrity — Does the user flow make sense end-to-end? Where does it break or dead-end?
3. Information density vs. noise — Are the stats, cards, and indicators actually useful? A dashboard showing "Setting Categories: 6" (a number that literally never changes) is noise.
4. Redundancy — Is the same concept implemented in multiple disconnected places? (e.g., discounts in both POS and Quote apps that don't talk to each other)
5. Progressive disclosure — Does the UI show the right amount at the right time, or does it dump everything at once?
6. Missing essentials — What's obviously needed but not there? A communication log that can't send communications. A customer picker that's a raw UUID field.

Step 4: Apply the Steve Jobs Lens

For each feature area, answer: if we removed this, would the product be worse? If not, it shouldn't be there. Force the hard call — keep only 3 features per area. This is deliberately painful. It reveals what's core vs. what's accumulated.

Audit Output Structure

For the exact output structure, read references/output-templates.md before writing the audit deliverable.

What Makes a Great Audit

• Code evidence for every claim. Don't say "the UI is confusing" — say "app/page.tsx:89 shows a stat card counting 'Setting Categories' — a static structural number that will never change."
• The user scenario. Don't say "there's no connection between tickets and work orders" — say "A tech starting work on ticket #142 has no way to know work order #38 exists, and vice versa."
• Genuine credit where earned. The audit isn't a hit job. If the three-tier quote pricing is genuinely innovative, say so and explain why.
• Scaffolds identified honestly. If the main content area is a placeholder div with a "will render here once API routes are migrated" comment, call it what it is — a scaffold dressed as an app.

---

Stage 2: Product Roadmap

The roadmap answers: what should this become, and in what order?

How to Build the Roadmap

Step 1: Develop the Product Thesis

This is the most important step and the one most often skipped. The thesis is a one-paragraph statement that defines what the product IS and what makes it different from generic alternatives.

Bad thesis: "We need to improve the CRM with better features and integrations." Good thesis: "A computer repair shop CRM is not a sales funnel. It's a device relationship ledger. The device IS the relationship — 'we fixed your Dell XPS screen last March' is more valuable than any lead score."

The thesis should:

• Be specific to the business context (not applicable to any random company)
• Identify the core insight that everything else flows from
• Explain why generic solutions (Salesforce, HubSpot, etc.) miss the point for this specific use case

Ask the user to help articulate this. Push back on generic theses. If they say "we need better customer management," ask: what makes YOUR customers different from a SaaS company's customers?

Step 2: Design What Each Feature SHOULD Be

Don't just flag gaps — design the solution. For each major area:

• Current state — what exists today (reference the audit)
• What it should do — specific, concrete behavior changes
• Why — connected back to the thesis
• The data model changes — what tables, fields, relationships need to exist?

Be specific enough that an engineer could start building from your description. Include field names, API endpoint shapes, UI layout descriptions.

Step 3: Map Cross-App Integration Points

For each pair of apps that should talk to each other:

• What's the current state of integration?
• What events or data should flow between them?
• What's the user scenario that requires the integration?

Step 4: Phase by Dependency, Not Priority

Don't organize phases as "P0, P1, P2" by importance. Organize by what MUST exist before the next thing can be built.

Example: You can't build "segment actions" until segments exist. You can't build "device-aware upsell" until devices are first-class entities. Phase by the dependency chain.

Step 5: Define the Hard Nos

Every roadmap needs explicit boundaries — what the product should NOT become. These prevent scope creep and keep the thesis intact.

Good hard nos are tempting features that feel like progress but would dilute the product:

• "Hard No: Lead Scoring and Sales Funnels — this is not a B2B SaaS sales team"
• "Hard No: Full Email Marketing Campaign Builder — Mailchimp exists"
• "Hard No: Custom Field Builder — if a field matters, identify it specifically and add it intentionally"

Roadmap Output Structure

For the exact output structure, read references/output-templates.md before writing the roadmap deliverable.

---

Stage 3: Sprint Plan with PM Gates

The sprint plan answers: exactly what gets built, in what order, with what checkpoints?

Sprint Plan Principles

1. 1-week sprints. Long enough to ship something meaningful, short enough to course-correct.

2. Sprint 0 is always planning. No code. Just PM alignment, branch strategy, dependency verification, and answers to the first PM decision gate. This sprint prevents the most expensive mistakes.

3. PM Decision Gates between every phase. These are 5-6 business questions that must be answered in writing before the next phase begins. They are the backbone of the plan.

4. Phase Definitions of Done are user-observable behavior changes. Not "sprints complete" — a narrative scenario. "A staff member opens the new-quote form, types 'Sarah' into the customer field, and sees Sarah Chen appear with her VIP badge and score of 82 — without typing a UUID."

5. Every deliverable has a file path. An engineer who's never seen the codebase should be able to execute from the sprint plan. Specify exact file paths for every component, migration, API route, and test file.

6. Cross-app impact tracked per sprint. A table showing which apps/packages are touched by each sprint prevents surprise breakage.

How to Build the Sprint Plan

Step 1: Break Phases Into 1-Week Sprints

Each sprint needs:

### Sprint {ID}: {Name}
**Phase:** {N}
**Duration:** 1 week
**Depends on:** {previous sprint(s)}

**Goal:** {One sentence — what the user can do after this sprint that they couldn't before}

**Deliverables:**
- [ ] `{exact/file/path.ext}` — {what this file does, in enough detail to build from}
- [ ] `{exact/file/path.ext}` — {description}
{repeat for every file that needs to be created or modified}

**Acceptance Criteria:**
- {Specific, testable condition — not "it works" but "typing 3+ characters returns results within 400ms"}
- {Another condition}
- {TypeScript compilation check: `npm run typecheck` passes in affected workspaces}

**Estimated Complexity:** Low / Medium / High
**Risk:** {What could go wrong, and what to check before starting}

**Other apps affected:** {list apps that consume or emit events/APIs touched by this sprint}

Step 2: Write PM Decision Gates

PM gates go between phases. They contain 5-6 questions that force real business decisions.

What makes a good PM question:

• Customer experience decisions: "When a score drops, do we show which component changed?"
• Business thresholds: "At what dollar amount does 'upgrade component' become 'buy a new machine'?"
• Data visibility: "Should customers see their own device spend history?"
• Automation vs. human judgment: "Auto-send re-engagement emails, or queue for staff approval?"
• Naming and language: "From name on outreach emails — generic business address or technician-specific?"
• Inventory: "When a stock clerk scans an item and the system shows 12 in stock but the shelf has 8, should the cycle count automatically create a discrepancy alert, or should it require the clerk to explicitly flag it? Auto-alerting catches more errors but creates alert fatigue."
• Scheduling: "If a customer no-shows three times, should the system block future online bookings and require phone-only scheduling? This protects staff time but risks losing the customer entirely."
• POS: "When a checkout total exceeds $500, should the system require manager approval before completing the transaction? This prevents unauthorized large sales but adds friction to legitimate high-value purchases like custom builds."

What makes a bad PM question:

• Engineering questions: "Should we use Redis or PostgreSQL for the queue?"
• Obvious answers: "Should we have a search function?"
• Questions that don't change the build: "What color should the button be?"

Each gate should include context for why the question matters — what breaks or gets built differently based on the answer.

Step 3: Write Phase Definitions of Done

Each phase ends with a narrative definition of done — a story of a real user doing real things. This replaces checkbox-style completion criteria.

Example: "A staff member clicks the 'At-Risk' segment card, sees 18 customers who haven't visited in 60+ days, selects all 18, picks the 'We Miss You' email template, and clicks Queue. The Closer agent picks up the tasks within a minute, resolves each customer's first name and last device, and writes a composed message to each communication log."

Step 4: Build the Reference Tables

End the sprint plan with:

1. Timeline visualization — ASCII art showing weeks, sprints, and phases
2. Apps touched per sprint — matrix table showing which codebases each sprint modifies
3. Critical path — which sprints cannot be parallelized
4. Quick reference file map — tree view of key file paths with sprint annotations

Sprint Plan Output Structure

For the exact output structure, read references/output-templates.md before writing the sprint plan deliverable.

---

Running the Pipeline

Full Pipeline (recommended)

When the user wants a complete product strategy:

1. Ask clarifying questions first:

   • What app/module/codebase are we auditing?
   • What's the business context? (Who are the users? What problem does the product solve?)
   • Is there an existing roadmap or plan to build from, or starting fresh?
   • Where should the output files be saved?

2. Run Stage 1 (Audit): Read all source code. Cross-reference git history. Produce {APP}_PRODUCT_AUDIT.md.

3. Pause for user review. The audit reveals reality — the user may want to adjust scope before roadmapping.

4. Run Stage 2 (Roadmap): Build on audit findings. Develop thesis with user input. Produce {APP}_ROADMAP.md.

5. Pause for user review. The thesis and phase structure need buy-in before sprint planning.

6. Run Stage 3 (Sprint Plan): Break phases into 1-week sprints with PM gates. Produce {APP}_SPRINT_PLAN.md.

Partial Pipeline

The user may ask for just one stage:

• "Audit this app" → Run Stage 1 only. Still read all source code.
• "Create a roadmap" → Check if an audit exists. If not, suggest one first, or run a lighter audit inline. Then Stage 2.
• "Break this into sprints" → Check if a roadmap exists. If so, use it as input for Stage 3. If not, ask whether to roadmap first or work from the user's existing plan.

Key Behaviors

• Always read source code first. Even for a sprint plan, you need to understand what exists to plan what's next. File paths in sprint deliverables must reference real directories and naming conventions from the codebase.
• Ask the user to articulate the product thesis. Don't accept "make it better." Push for the core insight.
• PM gate questions must be answerable by a non-engineer. If your question requires understanding of database schemas to answer, reframe it.
• Every feature must earn its place. If you catch yourself adding a feature because "it would be nice," apply the Steve Jobs test — would removing it make the product worse?
• Specificity over generality. File paths, component names, API endpoints, migration numbers, line numbers. An engineer who's never seen the codebase should be able to execute from the sprint plan.
• Git history as reality check. A placeholder that's actively being worked on is different from one that's been abandoned for 6 months. Note the difference.