130 lines
4.4 KiB
Markdown
130 lines
4.4 KiB
Markdown
# Implementation Plan <ID>: <Title>
|
|
|
|
Status: proposed
|
|
|
|
Target executor: GPT-5.6-Terra
|
|
|
|
Feature roadmap: `docs/roadmap/features/<id>-<slug>.md`
|
|
|
|
Active plan location: `docs/roadmap/implementation.md`
|
|
|
|
## Objective
|
|
|
|
Summarize the implementation outcome. The feature roadmap remains authoritative
|
|
for scope, rationale, target end state, and acceptance criteria.
|
|
|
|
## Execution Rules
|
|
|
|
- Execute stages in numeric order.
|
|
- Number stages with consecutive integers beginning with `Stage 1`. Do not use
|
|
zero-based, decimal, nested, or nonsequential stage identifiers.
|
|
- Before each stage, confirm its preconditions and the working-tree state of
|
|
its owning repository.
|
|
- Before each stage, read every document listed in that stage's Required Policy
|
|
Review. Do not rely on policy recalled from an earlier stage.
|
|
- Preserve unrelated and pre-existing changes.
|
|
- Do not make unresolved product or architecture decisions during execution;
|
|
stop and report the decision required.
|
|
- Start from the feature roadmap's simplest viable implementation. Trust
|
|
module-provided idempotence, change detection, check-mode behavior, and
|
|
error handling rather than reproducing them with preliminary probes or
|
|
supplemental state.
|
|
- Do not add a task merely for defensive completeness. Every probe, fact,
|
|
checksum, custom `changed_when`, shell or command invocation, sidecar state
|
|
file, staging layer, or abstraction must be required by an
|
|
acceptance criterion and must solve behavior that a direct module does not.
|
|
- Run every stage's validation before committing it.
|
|
- Commit each completed stage when it leaves the repository in a valid state,
|
|
using the commit intent specified by that stage.
|
|
- Do not begin a dependent stage after an earlier stage fails validation.
|
|
|
|
## Starting State and Preconditions
|
|
|
|
- List required branches, revisions, tools, dependencies, and prior features.
|
|
- Identify expected clean or intentionally dirty working trees.
|
|
|
|
## Repository Scope
|
|
|
|
- List every repository that may change and the changes it owns.
|
|
- List repositories that may be inspected but must remain unchanged.
|
|
|
|
## Stage 1: <Independently Verifiable Outcome>
|
|
|
|
### Objective
|
|
|
|
State the single outcome delivered by this stage.
|
|
|
|
### Required Policy Review
|
|
|
|
Before beginning this stage, read:
|
|
|
|
- `AGENTS.md`
|
|
- `docs/orientation.md`
|
|
- `docs/conventions.md`
|
|
- `<docs/ansible.md, docs/testing.md, and/or docs/planning.md as applicable>`
|
|
|
|
Replace the placeholder with every specialized policy applicable to this
|
|
stage. Include `docs/ansible.md` for Ansible design or implementation,
|
|
`docs/testing.md` for test work, and `docs/planning.md` for workspace planning
|
|
or progress management. Do not list an inapplicable policy merely for
|
|
completeness.
|
|
|
|
### Preconditions
|
|
|
|
- List facts that must be true before editing begins.
|
|
|
|
### Owning Repository
|
|
|
|
`<repository path>`
|
|
|
|
### Required Changes
|
|
|
|
1. Describe concrete behavior to implement, including relevant files or
|
|
components where known.
|
|
2. State invariants, compatibility requirements, and explicit exclusions.
|
|
3. Give the expected module-driven task flow. Call out every required use of
|
|
`command`, `shell`, state inspection, or manual change detection.
|
|
|
|
### Validation
|
|
|
|
Run:
|
|
|
|
```text
|
|
<exact validation command>
|
|
```
|
|
|
|
Expected result: describe the required observable outcome, not merely a zero
|
|
exit code.
|
|
|
|
### Completion Criteria
|
|
|
|
- List the evidence required before this stage is complete.
|
|
|
|
### Commit
|
|
|
|
Commit intent: `<type and concise purpose>`
|
|
|
|
## Stage 2: <Next Independently Verifiable Outcome>
|
|
|
|
Repeat the complete stage structure above. Add, remove, or split stages so
|
|
each is ordered by dependency, reviewable on its own, and small enough to
|
|
diagnose without repeating unrelated work. Continue with `Stage 3`, `Stage 4`,
|
|
and subsequent consecutive integers as needed.
|
|
|
|
## Final Validation and Handoff
|
|
|
|
- Run cross-stage and cross-repository validation required by the feature
|
|
roadmap.
|
|
- Confirm every changed repository is clean and identify all resulting commit
|
|
hashes.
|
|
- Summarize deviations from this plan, unresolved findings, and deferred work.
|
|
- Report any implementation complexity added beyond the planned task flow and
|
|
the acceptance criterion that required it.
|
|
- Do not mark the feature `done`; implementation results require review first.
|
|
|
|
## Progress Notes
|
|
|
|
Keep only concise current state, completed stage references, and blockers here.
|
|
Git history and implementation commits should preserve detailed execution
|
|
evidence.
|