Windsurf rules

1---
2name: survey-context
3model: haiku
4description: "Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first."
5---
6 
7# Survey Context
8 
9Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
10 
11> **Use this vs map-codebase:** `survey-context` consumes existing specs and docs (fast; does not re-derive). `map-codebase` builds the tech-stack doc from scratch by scanning the codebase. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
12 
13> **HARD GATE** — Read specs/ files before suggesting next steps. If state.yaml is stale or contradicts the codebase, request clarification rather than assuming intent.
14 
15Orchestrate-project 6 phases: Phase 1 Discover - Phase 2 Elaborate - Phase 3 Plan - Phase 4 Build - Phase 5 Verify - Phase 6 Release
16 
17## Process
18 
19> **Timing:** `bash scripts/bp-timing.sh start survey-context` at invocation; `bash scripts/bp-timing.sh end survey-context` before handoff.
20 
21### 1. Read CONVENTIONS.md
22 
23If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
24 
25### 2. Read specs/ (YAML-first)
26 
27Scan the `specs/` directory if it exists:
28 
29```
30specs/
31├── state.yaml                  → session: active_flow, epic, git, handoff
32├── release-plan.yaml           → target version, WSJF epic index
33├── execution-status.yaml       → flat story/epic status
34├── planning-status.yaml        → discover-phase checklist (optional)
35├── requirements/
36│   ├── VISION_LATEST.yaml
37│   ├── SCOPE_LATEST.yaml
38│   └── GLOSSARY_LATEST.yaml
39├── plans/                      → TECH_STACK, TEST_PLAN, etc.
40├── epics/                      → eNN shards (flat yaml or eNN/stories/)
41└── bugs/                       → BUG-*.md + registry.yaml
42```
43 
44For each YAML file found, note: exists? keys populated? `handoff.next_skill`?
45 
46Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if YAML exists.
47 
48→ verify: `bash scripts/validate-specs-yaml.sh`
49 
50### 3. Read CLAUDE.md
51 
52If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
53 
54### 4. Check git state
55 
56```bash
57git status --short
58git log --oneline -5
59git branch --show-current
60```
61 
62Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
63 
64### 5. Map the lifecycle phase
65 
66Based on what you've found, identify which PMBOK phase this project is currently in:
67 
68| Phase | Signals |
69|-------|---------|
70| **Discover** | No `requirements/SCOPE_LATEST.yaml` yet, or only rough notes |
71| **Design** | SCOPE exists but no `release-plan.yaml` |
72| **Plan** | `release-plan.yaml` exists; on `main`/`master` branch |
73| **Initiate** | On a feature branch; no code changes yet |
74| **Execute** | `state.yaml` `active_flow: build_epic`; epic capsule in progress |
75| **Verify** | Implementation done; run `verify-work` or `run-evals` |
76| **Bug** | `state.yaml` `active_flow: fix_bug` or open `specs/bugs/BUG-*.md` |
77| **Review** | All code written; no PR yet |
78| **Integrate** | PR open; tests passing |
79| **Sustain** | Ongoing; no active task |
80 
81Prefer `specs/state.yaml` `active_flow` and `handoff.next_skill` when present.
82 
83### 6. Suggest next skill
84 
85Based on the phase and state, recommend the most useful next step:
86 
87- **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
88- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan` or `ship-epic`.
89- **If in Execute phase**: Suggest `ship-epic` (resume) or `develop-tdd` for `active_story_id`.
90- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals`.
91 
92Example:
93```
94Phase: Execute
95Active branch: feat/e02-verify (state.yaml matches)
96release-plan.yaml: v3.0.0, 10 epics
97active_epic_id: e02
98 
99Suggested next: ship-epic (resume e02s01 at develop-tdd)
100```
101 
102Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
103 
104### 7. Surface blockers
105 
106If something looks wrong:
107- Broken tests in the baseline
108- Open `specs/bugs/BUG-*.md` with no active fix branch
109- Epic shards missing `verify:` on tasks
110- `validate-specs-yaml.sh` fails
111- Git hash in `state.yaml` stale vs `git rev-parse`
112 
113Report blockers first, before recommendations.
114 
115### 8. Record story start timestamp
116 
117At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
118 
119## Utility outputs
120 
121### list-epics (absorbed)
122 
123Loop through all `specs/epics/*/epic.yaml` files and print a summary of story counts per epic. Useful for understanding overall project scope and epic distribution.
124 
125### check-gates (absorbed)
126 
127Print the current `active_flow` from `specs/state.yaml`, run `bash scripts/validate-specs-yaml.sh` to verify YAML integrity, and show `git status` to report uncommitted changes and branch state. Use before handoffs or context transitions.
128 
129## Handoff
130 
131Gate: READY -> next: plan-work
132Writes: state.yaml handoff.next_skill = plan-work
133 
134 
135<!-- story: e03s03 -->
136