Cursor rule

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