---
title: Project Handbook – Planning Session Prompt
type: prompt-template
mode: planning
tags: [project-handbook, planning, discovery]
---

You are an AI agent preparing a planning/discovery session inside the project handbook.  

## Your Rules
1. **Stay in planning mode.** Do not mutate code or run implementation commands unless explicitly instructed.  
2. **Load continuity context.** Read `.project-handbook/AGENT.md`, `.project-handbook/process/sessions/logs/latest_summary.md`, and the newest recap in `.project-handbook/process/sessions/session_end/session_end_index.json` before planning.  
3. **Work inside the handbook repo.** Use `ph ...` automation from any directory (pass `--root` if needed).  
4. **Use `.project-handbook/process/AI_AGENT_START_HERE.md`** as your canonical workflow guide.  
5. **Surface dependencies and follow-ups.** If you propose new work, add it via handbook commands (e.g. `ph feature create`, `ph parking add`) instead of free-form notes.  
6. **Document insights.** Update feature/task docs (status, architecture, implementation) so execution sessions have everything they need.  
7. **Plan bounded sprints by lanes.** Prefer work-boundary lanes + explicit integration tasks over weekly timeboxes; keep points for telemetry, not as a cap.
8. **Scope tasks with zero ambiguity.** Execution tasks must not contain open questions, “optional” scope, or `TBD`; discovery questions must be captured as `task_type=research-discovery` tasks referencing a `DR-XXXX`.
9. **Use the Decision Register workflow.** Decisions are created/completed inside `task_type=research-discovery` tasks as `DR-XXXX` entries, routed to either:
   - feature-scoped: `.project-handbook/features/<feature>/decision-register/DR-XXXX-<slug>.md`
   - cross-cutting: `.project-handbook/decision-register/DR-XXXX-<slug>.md`
   After operator approval, promote the accepted decision into an **FDR** (feature-local) or **ADR** (cross-cutting) and create execution tasks that reference the ADR/FDR (not the DR).
10. **Session routing rule.** If you are working from a sprint task directory, check `task.yaml task_type:`. Session template is derived from `task_type`. If the derived session does not match this prompt, stop and restart using `ph onboarding session <derived-session>` (or run `ph task show --id TASK-XXX` to see the derived session).
11. **Non-interactive contract.** Do not ask the user questions in sprint planning. If absolutely blocked by missing info that cannot be derived from handbook artefacts, capture it via `ph question add` and stop.
12. **No web/deep research here.** Web search / DeepWiki / LSP-style exploration belongs only in `task_type=research-discovery` tasks.

## Planning Checklist
- Load context (continuity + guard rails):  
  ```bash
  cat .project-handbook/AGENT.md
  cat .project-handbook/process/AI_AGENT_START_HERE.md
  cat .project-handbook/process/sessions/logs/latest_summary.md
  cat .project-handbook/process/sessions/session_end/session_end_index.json
  ```  
- Review release context (only if a release is active):  
  ```bash
  # Prints releases/current/plan.md + sprint-slot breakdown + gate burn-up, and refreshes releases/current/progress.md
  # For tooling/cat/grep: `.project-handbook/releases/current.txt` contains the active release version.
  # Note: release readiness is gate-first; feature completion is historical context.
  ph release show
  ```  
- Review current sprint/feature context:  
  ```bash
  ph sprint status
  ph feature summary
  ```  
- Draft a lane-based sprint shape:
  - Define 2–6 lanes (separate concerns/services)
  - Add explicit integration tasks (cross-lane dependencies)
  - Use story points for throughput/velocity tracking (do not limit sprint scope by points)
- Inspect relevant feature/task docs under `.project-handbook/features/<feature>/`.  
- Draft or refine architecture/implementation plans (Mermaid diagrams, tables, acceptance criteria, dependencies).  
- Capture follow-up work:  
  ```bash
  ph parking add ...
  ph backlog add ...
  ```  
- Ensure a sprint exists (task creation requires a current sprint):
  ```bash
  ph sprint plan
  ```
- Sprint gate (required; exists from Day 0, closes last):
  - `ph sprint plan` scaffolds a sprint gate task if one does not already exist.
  - Fill in `validation.md` early (goal + exit criteria + evidence), but expect to mark it `done` last.
  - If you need to create one manually:
  ```bash
  ph task create --title "Sprint Gate: <goal>" --feature <feature> --decision ADR-XXXX --type sprint-gate --points 3
  ```
- Create execution-ready sprint tasks (use `--type research-discovery` for investigation/discovery tasks):  
  ```bash
  # If a release is active, tag tasks with `release=current` so release reporting reflects reality.
  ph dr add --id DR-0001 --title "<question title>" --feature <feature>
  ph task create --title "Investigate: <question>" --feature <feature> --decision DR-0001 --type research-discovery --release current
  ph task create --title "Implement: <deliverable>" --feature <feature> --decision ADR-XXXX --type implementation --release current
  ph task create --title "Release Gate: <name>" --feature <feature> --decision ADR-XXXX --points 3 --release current --gate
  ```  
- Ensure the sprint plan is release-aligned (only if a release is active):
  - Set `release: vX.Y.Z` and `release_sprint_slot: <n>` in `.project-handbook/sprints/current/plan.md` front matter to match `.project-handbook/releases/current/plan.md`.
  - For tooling/cat/grep: `.project-handbook/releases/current.txt` contains the active release version.
  - Explicitly list release-critical vs release-support vs non-release scope in the Sprint Plan (release is a measurement context, not an automatic scope cap).
  - Ensure the sprint has at least one **Gate** task that advances the release goals for that slot:
    - Official release gates (burn-up): `release_gate: true`
    - Rehearsal/diagnostic gates: keep `release: current` but set `release_gate: false`
- Update `status.md`, `risks.md`, or other feature documents with planning outcomes.  
- Run `ph validate` and `ph pre-exec lint` to ensure handbook consistency and doc determinism.  

## Deliverables
- Clear planning artefacts (architecture/implementation updates, diagrams, tables).  
- Logged dependencies with backlog item IDs.  
- Explicit next steps for execution sessions.  
- No code or infrastructure changes (unless requested).  

Remember: start at `.project-handbook/process/AI_AGENT_START_HERE.md`, follow the planning mode guidance, and leave the execution surface ready for the next agent.
