project-planning-structure

name	project-planning-structure
description	Project planning structure and milestone template patterns. Use when creating project plans, structuring milestones, or organizing project documentation.

Project Planning Structure Rules

Plan Location & Naming

1. Every VM type or cross-cutting concern gets a project plan in docs/projects/<date>-<seq>-<name>/project_plan.md. Plans are the contract between planning and implementation.

2. Without structure, milestones lack verify criteria, rollback procedures, and dependency tracking — leading to "it works on my machine" outcomes.

Milestone Structure Requirements

3. Every milestone MUST include three sections: tasks (checkbox items), verify (inline assertions to add to molecule), and rollback (how to undo the milestone).

4. Every milestone MUST declare its dependency status: self-contained (no external blockers) or blocked on (lists the blocking project/milestone).

5. Self-contained milestones come before blocked milestones in the ordering. Work that can ship now ships first.

6. Milestone 0 of any project that introduces new testing patterns MUST establish the test infrastructure before feature work begins.

Milestone Template Structure

7. Each milestone follows this structure:

### Milestone N: <Feature>
_Self-contained._ or _Blocked on: <project/milestone>._
Description.

See: `<skill-name>` skill.

**Implementation pattern:**
- Task file: `roles/<type>_configure/tasks/<feature>.yml`
- site.yml plays: (1) configure on `<dynamic_group>`, tag `<feature>` (2) deploy_stamp on `<flavor_group>`, tag `<feature>`
- Molecule scenario: `molecule/<type>-<feature>/`

- [ ] Task items

**Verify:**
- [ ] Assertions

**Rollback (`--tags <feature>-rollback`):**
Steps to reverse the feature (including auth/credential state if changed).

Milestone Dependency Graph

8. Every plan MUST include a Milestone Dependency Graph (ASCII tree) showing the ordering and blocking relationships at a glance.

## Milestone dependency graph
M0 (test infra)
├── M1 (security) ← self-contained
├── M2 (VLANs) ← self-contained
├── M3 (encrypted DNS) ← self-contained
├── M4 (mesh) ← self-contained
├── M5 (pihole DNS) ← blocked on Pi-hole LXC project
└── M8 (docs + integration)

Standard Work Cycle Per Milestone

9. Every milestone that changes images or configure roles MUST follow the 6-step standard work cycle:

   • Step 1: Update build-images.sh
   • Step 2: Build images IN PARALLEL on test units (REQUIRED — 6 hosts available)
   • Step 3: Write tests and playbook updates while images build
   • Step 4: Run E2E molecule test after images are ready
   • Step 5: Code review while E2E runs (DRY, ARCH, KISS, OOP, test quality)
   • Step 6: Manual playbook verification after E2E passes

   No rollback strategy needed — old image versions are saved and we can just rebuild. Straightforward clean management.

   NEVER skip Step 2. NEVER add legacy fallback code in configure roles.

Milestone Sizing

10. Each milestone should be completable in a single focused session (2-4 hours). If a milestone has more than 8-10 checkbox items, split it. If it has fewer than 3, merge it with an adjacent milestone.

Blocked Milestone Handling

10. Blocked milestones SHOULD still be fully specified — they're ready to implement the moment the blocker is resolved.

11. When implementing a project, blocked milestones SHOULD be moved to their downstream projects rather than kept as stubs. Stubs in site.yml, cleanup.yml, and task files create dead code that confuses future maintainers.

12. Previous bug: M5-M7 stubs (pihole_dns, syslog, monitoring) were implemented as task files + site.yml plays + cleanup.yml rollback plays, then had to be removed entirely because they belonged in their respective downstream projects.

Manual Testing Playbook Requirements

13. When a project includes manual testing (Standard Work Cycle Step 6), load and follow the manual-testing-playbook-writing skill for HOW to write the playbook. Key constraints enforced here in the plan structure:

    • The playbook MUST be written into docs/manual-testing-playbooks.md DURING plan creation — not deferred to implementation.
    • The project plan references the playbook by file path and section number (e.g., "EXECUTE Playbook 13, sections 13.1–13.7"). NEVER duplicates playbook content inline.
    • The webui-manual-testing skill MUST be updated to list the new playbook immediately — not deferred to a later milestone.

    See: manual-testing-playbook-writing skill for exhaustive feature enumeration, section structure, prerequisites, and host-awareness rules.