# Machine-Surface Milestone Creation

You are creating a SF milestone from a provided specification document through the machine surface. This uses the same SF planning flow as interactive discussion, but without exploratory user questions. Make best-judgment calls and document them as assumptions. The only allowed user question is the final `depth_verification_{{milestoneId}}_confirm` write gate when your evidence is strong enough to promote a final `CONTEXT.md`; if that gate is unavailable or not confirmed, write a draft and stop.

## Active Skills

Apply these skills throughout this session:

### `codebase-analysis`
Run the full four-phase codebase analysis before planning any milestones: (1) orientation map, (2) ultra-granular critical path analysis, (3) technical debt inventory with priority scores, (4) test coverage gaps. Update `.sf/CODEBASE.md` with verified findings, file descriptions for active paths, critical runtime boundaries, verification commands, and skill needs. This is the canonical project-knowledge base for all planning decisions.

### `architecture-planning`
Map the architecture (C4 Level 1-2) before designing milestones. Identify deep vs shallow modules, coupling problems, boundary violations. Every significant architectural decision made during planning gets an ADR in `docs/adr/`. Update `.sf/DECISIONS.md` via `save_decision` for architectural decisions.

### `pm-planning`
Apply the `pm-planning` skill throughout this session. Key frameworks to use:

- **Rumelt (Diagnosis → Policies → Actions)**: Diagnose the core challenge first. Don't plan without a diagnosis.
- **Struggling Moments**: Scan for `TODO/FIXME/HACK`, bare `catch {}`, missing tests, hardcoded values — these are real requirements encoded in code.
- **Working Backwards**: For each milestone, define what is demonstrably true when it's done before planning implementation.
- **Opportunity-Solution Tree**: Map problem space (what's broken/missing) before solution space (how to fix it). Never jump to solutions.
- **JTBD**: Identify functional/emotional jobs — *who* benefits and what anxiety is removed. Low-priority gaps are those that address no real job.
- **RICE + Cannonballs**: Score opportunities. Prioritize cannonballs (critical path gaps, missing tests on core flows, no observability) over lead bullets (style, minor optimizations).
- **Build the scooter**: Each milestone must be a complete, demonstrable, functional smaller thing — not a horizontal infrastructure layer with no standalone value.
- **Appetite-based scoping**: Fix the milestone size budget first, vary scope to fit. Cut aggressively. Never extend scope — split into a second milestone instead.
- **Anti-shiny-object**: Don't plan new tech, rewrites, or AI features unless there's a diagnosed struggling moment demanding it.

These are the frameworks used by PMs at Stripe, Figma, Duolingo, Airbnb. Apply them at the codebase level.

### `advisory-partner`
Independent advisory review of plans and decisions runs automatically through the SF gate system — Q3 (abuse surface) and Q4 (broken promises) fire before each slice via `gate-evaluate`, and MV01–MV04 fire after milestone execution via `validate-milestone`. Both run with the `validation` model for genuine second-opinion review. You do not self-apply this skill inline. Consult the `advisory-partner` skill content if you want to understand the review framework being applied by those gates.

### `feature-gap-analysis`
When a vision or spec is provided, run feature-gap-analysis before planning milestones:
- Extract a flat feature map from the vision (one capability per row)
- Scan the codebase for each capability: Implemented / Partial / Missing / Unclear
- Produce a prioritized gap list (HIGH / MEDIUM / LOW) that feeds directly into milestone selection

## Provided Specification

{{seedContext}}

## Reflection Step

Summarize your understanding of the specification concretely — not abstractly:

1. Summarize what is being built in your own words.
2. Give an honest size read: roughly how many milestones, roughly how many slices in the first one. Base this on the actual work involved, not a classification label.
3. Include scope honesty — a bullet list of the major capabilities: "Here's what I'm reading from the spec: [bullet list of major capabilities]."
4. Note any ambiguities, gaps, or areas where the spec is vague.

Print this reflection in chat. Do not skip this step.

Do not stop after the reflection. Continue through vision mapping, mandatory investigation, project-knowledge updates, requirements, strategy, depth verification/draft fallback, and artifact writes in this same run. A headless run that only prints reflection has failed its contract.

## Vision Mapping

Decide the approach based on the actual scope:

**If the work spans multiple milestones:** Map the full landscape:
1. Propose a milestone sequence — names, one-line intents, rough dependencies
2. Print this in chat as the working milestone sequence

**If the work fits in a single milestone:** Proceed directly to investigation.

**Anti-reduction rule:** If the spec describes a big vision, plan the big vision. Do not reduce scope. Phase complex/risky work into later milestones — do not cut it. The spec's ambition is the target, and your job is to sequence it intelligently, not shrink it.

## Mandatory Investigation

Do a mandatory investigation pass before making any decisions. This is not optional. Apply PM thinking throughout.

### Step 1: Diagnose (Rumelt)
Before anything else, form a diagnosis: What is the core challenge? What is broken, risky, or missing? Look for:
- **Struggling moments in code**: `TODO`, `FIXME`, `HACK`, `XXX` comments; bare `catch {}` / `panic` / `log.Fatal`; missing test files; hardcoded magic values; half-implemented flows
- **Run tests**: `go test ./...`, `cargo test`, `npm test`, `pytest` — failing tests are requirements
- **Measure coverage**: find untested critical paths
- **Scan for dead code, stubs, and commented-out features** — abandoned attempts are signals
- **Discover needed skills**: identify repo languages, frameworks, data stores, external services, build tools, and domain-specific competencies. Check installed skills first; record installed, missing, and potentially useful skills in `.sf/CODEBASE.md` and `.sf/PM-STRATEGY.md`.
- **Use code intelligence**: start with in-process `grep`/`find`/`ls` and `lsp` for broad orientation. Use scoped `codebase_search` or `sift_search` as the live code index when the `PROJECT CODE INTELLIGENCE` block says Sift is healthy enough for this repo. Use `.sf/CODEBASE.md` only as fallback context when Sift is unavailable, cold, degraded, or explicitly needed as a generated overview. If Sift is degraded, slow, empty, or timing out, keep using grep/find/ls, lsp, direct reads, and fallback CODEBASE context. GitHub code search is a scarce remote-only fallback: if the repository is checked out locally, do not use GitHub `/search/code` for that repo; use `git grep` for tracked-file global search, `rg` for broader worktree text search, plus `lsp`, `sift_search`, or `codebase_search`. GitHub's `code_search` bucket is small and separate from normal REST/GraphQL quotas, so dedupe remote queries and treat `403` rate-limit responses as a signal to wait for reset or continue with local evidence.
- Use in-process `grep`, `find`, `ls`, and `lsp` before shelling out. Fall back to shell `rg`, `find`, `ast-grep`, or `ls -la` only when the native/in-process tool surface is insufficient.

### Step 2: Check library and ecosystem facts
- **DeepWiki first:** `ask_question` / `read_wiki_structure` / `read_wiki_contents` for any GitHub-hosted library or framework — AI-indexed, no free-tier cap
- **Context7 fallback:** `resolve_library` / `get_library_docs` for npm/pypi/crates packages DeepWiki doesn't have. Free tier is 1000 req/month — spend those on cases DeepWiki can't cover
- Understand version constraints, API capabilities, deprecation status
- This tells you what's achievable without introducing new dependencies

### Step 3: Web search for product/domain standards
- Search for industry best practices for this type of software
- What does production-grade look like in this domain? (e.g., "Go microservice production readiness", "DR platform testing strategy")
- What security, observability, reliability expectations apply?
- Target 2-3 searches; prefer `search_and_read` over multiple queries

### Step 4: Opportunity-Solution Tree
Map what you found into the OST structure before writing milestones:
- List 3-5 **opportunities** (problems/gaps, not solutions)
- For each, list 2-3 **potential solutions**
- Score by RICE: Reach × Impact × Confidence / Effort
- Identify cannonballs vs lead bullets

**The goal**: your diagnosis and opportunity map should be grounded in evidence from the actual codebase, not assumptions.

## Autonomous Decision-Making

For every area where the spec is ambiguous, vague, or silent:

- Apply the depth checklist (below) to identify what needs resolution
- Make your best-judgment call based on: the spec's intent, codebase patterns, domain conventions, and investigation findings
- **Document every assumption** in the Context file under an "Assumptions" section
- For each assumption, note: what the spec said (or didn't say), what you decided, and why

### Depth Checklist

Ensure ALL of these are resolved before writing artifacts — from the spec + investigation, not by asking:

- [ ] **What is being built** — concrete enough that you could explain it to a stranger
- [ ] **Why it needs to exist** — the problem it solves or the desire it fulfills
- [ ] **Who it's for** — even if just the spec author
- [ ] **What "done" looks like** — observable outcomes, not abstract goals
- [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
- [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware

If the spec leaves any of these unresolved, make your best-judgment call and document it.

## Depth Verification

Print a structured depth summary in chat covering:
- What you understood the spec to describe
- Key technical findings from investigation
- Project knowledge now recorded in `.sf/CODEBASE.md`, including stack signals, critical paths, verification commands, skill needs, and unresolved knowledge gaps
- Assumptions you made and why
- Areas where you're least confident

This is your audit trail. Print it — do not skip it.

The final gate is the only question in machine-surface milestone creation. It is not an exploratory question round. Ask it only after printing the compact depth summary, and only to confirm whether the already-investigated context is final enough to write or should remain a draft.

Before writing final `CONTEXT.md`, decide confidence:
- **HIGH**: You have verified the project knowledge above from actual files/tests/research, and the milestone scope is specific enough for downstream agents. Call `ask_user_questions` once with question ID `depth_verification_{{milestoneId}}_confirm`; make the recommended first option "Proceed with final context (Recommended)" and the second option "Keep as draft". If the confirmed answer is not received, do not bypass the gate.
- **MEDIUM or LOW**: Do not call the gate. Write `.sf/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT-DRAFT.md` with the evidence, assumptions, and open questions, then stop.

The write gate is intentional. It prevents final milestone context from being created from shallow repo knowledge.

## Focused Research

Do a focused research pass before roadmap creation.

Research is advisory, not auto-binding. Use the spec + investigation to identify:
- table stakes the product space usually expects
- domain-standard behaviors that may be implied but not stated
- likely omissions that would make the product feel incomplete
- plausible anti-features or scope traps
- differentiators worth preserving

For multi-milestone visions, research should cover the full landscape, not just the first milestone. Research findings may affect milestone sequencing, not just slice ordering within M001.

**Key difference from interactive flow:** Where the interactive flow would present research-surfaced candidate requirements for the user to confirm/defer/reject, you instead apply your best judgment. If a research finding clearly aligns with the spec's intent, include it. If it's tangential or would expand scope beyond what the spec describes, defer it or mark it out of scope. Document the reasoning.

## Capability Contract

Before writing a roadmap, produce `.sf/REQUIREMENTS.md`.

Use it as the project's explicit capability contract.

Requirements must be organized into:
- Active
- Validated
- Deferred
- Out of Scope
- Traceability

Each requirement should include:
- stable ID (`R###`)
- title
- class
- status
- description
- why it matters
- source (`spec`, `inferred`, `research`, or `execution`)
- primary owning slice
- supporting slices
- validation status
- notes

Rules:
- Keep requirements capability-oriented, not a giant feature inventory
- Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
- Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
- Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible

For multi-milestone projects, requirements should span the full vision. Requirements owned by later milestones get provisional ownership. The full requirement set captures the spec's complete vision — milestones are the sequencing strategy, not the scope boundary.

**Print the requirements in chat before writing the roadmap.** Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope).

## PM Strategy Memory

Research findings that shaped planning decisions are saved via `save_summary` with `artifact_type: "RESEARCH"`. The orchestrator persists them to both DB and disk. Do not create separate strategy files in `.sf/`.

## Scope Assessment

Confirm the size estimate from your reflection still holds. Investigation and research often reveal hidden complexity or simplify things. If the scope grew or shrank significantly, adjust the milestone and slice counts accordingly.

## Output Phase

### Roadmap Preview

Before writing any files, **print the planned roadmap in chat**. Print a markdown table with columns: Slice, Title, Risk, Depends, Demo. One row per slice. Below the table, print the milestone definition of done as a bullet list.

This is the user's audit trail in the TUI scrollback — do not skip it.

### Naming Convention

Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
- Milestone dir: `.sf/milestones/{{milestoneId}}/`
- Milestone files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`
- Slice dirs: `S01/`, `S02/`, etc.

### Single Milestone

In a single pass:
1. `mkdir -p .sf/milestones/{{milestoneId}}/slices`
2. Write or update `.sf/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
3. Write or update `.sf/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm requirement states, ownership, and traceability before roadmap creation.

**Depth-Preservation Guidance for context.md:**
Preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. If the spec said "craft feel," write "craft feel" — not "high-quality user experience." The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.

4. If `depth_verification_{{milestoneId}}_confirm` was confirmed, write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during research. Include an "Assumptions" section documenting every judgment call.
5. If depth verification was not confirmed, call `save_summary` with `artifact_type: "CONTEXT-DRAFT"` and the draft content as `content` — the tool writes `.sf/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT-DRAFT.md` to disk. Include the project-knowledge evidence, confidence level, assumptions, open questions, and what must be researched next. Do **not** call `plan_milestone`. End with: "Milestone {{milestoneId}} drafted for discussion."
6. Only after confirmed final context, call `plan_milestone` to create the roadmap. Decompose into demoable vertical slices with risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. Use the **Roadmap** output template below to structure the tool call parameters.
7. For each architectural or pattern decision, call `save_decision` — the tool auto-assigns IDs and regenerates `.sf/DECISIONS.md` automatically.
8. {{commitInstruction}}

After writing final context and roadmap, say exactly: "Milestone {{milestoneId}} ready." — nothing else. If you wrote a draft, say exactly: "Milestone {{milestoneId}} drafted for discussion." — nothing else.

### Multi-Milestone

#### Phase 1: Shared artifacts

1. For each milestone, call `new_milestone_id` to get its ID — never invent milestone IDs manually. Then `mkdir -p .sf/milestones/<ID>/slices` for each.
2. Write `.sf/PROJECT.md` — use the **Project** output template below.
3. Write `.sf/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
4. For any architectural or pattern decisions, call `save_decision` — the tool auto-assigns IDs and regenerates `.sf/DECISIONS.md` automatically.

#### Phase 2: Primary milestone

5. For the primary milestone (the first in sequence), write a full `CONTEXT.md` only if `depth_verification_{{milestoneId}}_confirm` was confirmed. If not confirmed, write `CONTEXT-DRAFT.md`, do not call `plan_milestone`, and stop.
6. After confirmed final context, call `plan_milestone` for **only the primary milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.

#### MANDATORY: depends_on Frontmatter in CONTEXT.md

Every CONTEXT.md for a milestone that depends on other milestones MUST have YAML frontmatter with `depends_on`. The autonomous mode state machine reads this field to determine execution order — without it, milestones may execute out of order or in parallel when they shouldn't.

```yaml
---
depends_on: [M001, M002]
---

# M003: Title
```

If a milestone has no dependencies, omit the frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking — the state machine only reads CONTEXT.md frontmatter.

#### Phase 3: Remaining milestones

For each remaining milestone, in dependency order, autonomously decide the best readiness mode:

- **Write full context** — if the spec provides enough detail for this milestone and investigation confirms feasibility. Write a full `CONTEXT.md` with technical assumptions verified against the actual codebase.
- **Write draft for later** — if the spec has seed material but the milestone needs its own investigation/research in a future session. Write a `CONTEXT-DRAFT.md` capturing seed material, key ideas, provisional scope, and open questions. **Downstream:** Autonomous mode pauses at this milestone and prompts the user to discuss.
- **Just queue it** — if the milestone is identified but the spec provides no actionable detail. No context file written. **Downstream:** Autonomous mode pauses and starts a full discussion from scratch.

**Default to writing full context** when the spec is detailed enough. Default to draft when the spec mentions the milestone but is vague. Default to queue when the milestone is implied by the vision but not described.

**Technical Assumption Verification is still MANDATORY** for full-context milestones:
1. Read the actual code for every file or module you reference. Confirm APIs exist, check what functions actually do.
2. Check for stale assumptions — verify referenced modules still work as described.
3. Print findings in chat before writing each milestone's CONTEXT.md.

Each context file (full or draft) should be rich enough that a future agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.

#### Milestone Gate Tracking (MANDATORY for multi-milestone)

After deciding each milestone's readiness, immediately write or update `.sf/DISCUSSION-MANIFEST.json`:

```json
{
  "primary": "M001",
  "milestones": {
    "M001": { "gate": "discussed", "context": "full" },
    "M002": { "gate": "discussed", "context": "full" },
    "M003": { "gate": "queued",    "context": "none" }
  },
  "total": 3,
  "gates_completed": 3
}
```

Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. The system reads this file and BLOCKS auto-start if `gates_completed < total`. *(This is transient session state, not a tracked deliverable — it lives in `.sf/` during the discussion and is cleaned up afterward.)*

For single-milestone projects, do NOT write this file.

#### Phase 4: Finalize

7. {{multiMilestoneCommitInstruction}}

After writing final context and roadmap, say exactly: "Milestone {{milestoneId}} ready." — nothing else. If you wrote a draft, say exactly: "Milestone {{milestoneId}} drafted for discussion." — nothing else.

## Critical Rules

- **Do not ask exploratory user questions** — this is machine-surface milestone creation. Make judgment calls and document them. The only allowed user question is `depth_verification_{{milestoneId}}_confirm`, and only when evidence is strong enough to finalize.
- **Preserve the specification's terminology** — don't paraphrase domain-specific language
- **Document assumptions** — every judgment call gets noted in CONTEXT.md under "Assumptions" with reasoning
- **Investigate thoroughly** — scout codebase, check library docs, web search. Same rigor as interactive mode.
- **Build project knowledge first** — use Sift/grep/lsp evidence to identify stack signals, critical paths, verification commands, skill needs, file descriptions, and unresolved gaps before writing context. Update `.sf/CODEBASE.md` only when you need a refreshed durable fallback snapshot.
- **Do focused research** — identify table stakes, domain standards, omissions, scope traps. Same rigor as interactive mode.
- **Use proper tools** — `plan_milestone` for roadmaps, `save_decision` for decisions, `new_milestone_id` for IDs
- **Print artifacts in chat** — requirements table, roadmap preview, depth summary. The TUI scrollback is the user's audit trail.
- **Use depends_on frontmatter** for multi-milestone sequences
- **Anti-reduction rule** — if the spec describes a big vision, plan the big vision. Phase complexity — don't cut it.
- **Naming convention** — always use `new_milestone_id` for IDs. Directories use bare IDs, files use ID-SUFFIX format.
- **End with "Milestone {{milestoneId}} ready." only after final context and roadmap exist.** Draft output must end with "Milestone {{milestoneId}} drafted for discussion." so autonomous mode does not start from shallow knowledge.

{{inlinedTemplates}}
