---
name: planning
description: Use when the user wants to generate the F2 phase plan and milestones from Discovery artifacts. Reads the business proposal, RF/RNF index, and HLA, then writes docs/discovery/<project-slug>/planning/phase-plan.md. Triggers on "/machine-discovery:planning <project-slug>", "/planning <project-slug>", and requests for Discovery phase planning.
---

# Planning

Generate the F2 phase plan and milestones from the F1 Discovery artifacts.

## Inputs

```text
docs/discovery/<project-slug>/inputs/business-proposal.md
docs/discovery/<project-slug>/requirements/index.json
docs/discovery/<project-slug>/hla/hla.md
```

## Output

```text
docs/discovery/<project-slug>/planning/phase-plan.md
```

## Operating protocol

1. Parse `$ARGUMENTS` and resolve the output language.
   - The first token MUST be a kebab-case ASCII project slug.
   - A second token MAY be `es` or `en`; if present, it wins.
   - If a second token is present and is not `es` or `en`, stop with `NEEDS INPUT: language must be es or en`.
   - If no language argument is present, inherit `language` from `hla/hla.md`; otherwise from `requirements/requirements.md`; if missing, use the current user request language; if ambiguous, default to `es`.
   - If missing or invalid, stop with `NEEDS INPUT: indica el project slug, por ejemplo /machine-discovery:planning acme-demo`.
2. Validate prerequisites:
   - Business proposal exists and is non-empty.
   - Requirements index exists and has at least one RF.
   - `hla/hla.md` exists and is non-empty.
3. If `planning/phase-plan.md` already exists, ask before overwriting. Do not silently replace it.
4. Write `docs/discovery/<project-slug>/planning/phase-plan.blocks`.
   - The content file MUST contain one `@@KEY@@` block for each placeholder in `templates/phase-plan.<lang>.md.tmpl`, including `@@LANG@@`.
5. Create a phase plan that groups RFs into delivery phases and milestones. RNFs MUST appear as cross-cutting constraints or phase-specific gates.
   - `@@MILESTONES@@`: order milestones by client value/criticality — the highest-priority RFs (per their priority in `requirements/index.json`) land in the EARLIEST milestones. Target a ~3-month delivery window.
   - `@@EFFORT_ESTIMATE@@`: estimated hours per milestone. Hours with no basis MUST be `NEEDS INPUT`, never fabricated.
   - `@@CONTINGENCY_BUFFER@@`: an explicit contingency buffer (e.g. a percentage of total effort) on top of the estimate.
   - `@@TEAM_PROFILE@@`: roles (TL, FA, Dev, QA, …) and counts, coherent with the HLA stack.
   - `@@TOTAL_DURATION@@`: total F2 duration (estimated start/end) derived from effort + team profile. No fabricated calendar dates → `NEEDS INPUT`.
6. Unknown estimates, dates, staffing, or dependencies MUST be written as `NEEDS INPUT: <specific question>`.
7. Run `bash plugins/machine-discovery/scripts/assemble-doc.sh plugins/machine-discovery/skills/planning/templates/phase-plan.<lang>.md.tmpl docs/discovery/<project-slug>/planning/phase-plan.blocks docs/discovery/<project-slug>/planning/phase-plan.md`.
8. Delete `phase-plan.blocks` only after validating the assembled Markdown.
9. Score against [references/checklist.md](references/checklist.md). Pass criterion: 5/5. Fix and re-render any failed item.
10. Final report MUST print exactly `/machine-discovery:draft-prds <project-slug>` as the next-step suggestion. Do not run it.

## Hard rules

- **HLA required.** Do not generate phase planning before HLA exists.
- **RF traceability required.** Every phase MUST list the RF IDs it covers.
- **RNF gate required.** Every relevant RNF MUST be assigned to a phase gate or cross-cutting quality gate.
- **Effort in hours + buffer.** Every milestone MUST carry an hours estimate, and the plan MUST include an explicit contingency buffer. Unbased hours → `NEEDS INPUT`, never fabricated.
- **Team profile required.** The plan MUST define team roles and counts, coherent with the HLA stack.
- **Total duration required.** The plan MUST state total F2 duration derived from effort + team profile.
- **Milestones prioritized by value.** Milestones MUST be ordered so the highest-value/criticality RFs land in the earliest milestones.
- **No invented dates.** Do not create calendar dates unless sources provide them.
- **Script-owned Markdown.** Final planning Markdown MUST be assembled by `scripts/assemble-doc.sh` from `.blocks` and template.
- **Selected-language output.** Generated titles, body prose, and template-owned headings MUST match the resolved output language; verbatim source quotes stay unchanged.
- **No auto-chaining.** Do not run draft PRDs or later artifacts.
- **Namespaced next step.** Final user-facing next-step suggestion MUST be `/machine-discovery:draft-prds <project-slug>`.

## References

- Phase plan templates: [templates/phase-plan.es.md.tmpl](templates/phase-plan.es.md.tmpl), [templates/phase-plan.en.md.tmpl](templates/phase-plan.en.md.tmpl)
- Quality checklist: [references/checklist.md](references/checklist.md)
- Anti-patterns: [references/anti-patterns.md](references/anti-patterns.md)