Doc Iplan

doc-iplan

Purpose

Create an Implementation Plan (IPLAN) — Layer 8 of the SDD flow. An IPLAN bridges SPEC + TDD to source code: declares test-first file order (inherited from TDD), executable bash commands, session progress for stateless executors, and an audit trail from spec to delivered files.

Layer: 8 (final doc layer; downstream is Code). Upstream: SPEC, TDD (per the necessary-upstream contract; the rest of the chain is reachable transitively via SPEC/TDD's own @-tag references).

One IPLAN per SPEC component (matching its TDD). Bugfixes with no new functionality use a temporary plan in docs/08_IPLAN/tmp/ instead.

When to Use

Use doc-iplan when:

• Layers 1–7 exist and the source TDD has reached IPLAN-Ready ≥ 90/100.
• You are ready to bridge a SPEC/TDD component into source code.
• You need an executable, session-resumable plan for stateless coding agents.

For end-to-end generation from a SPEC/TDD, a prompt, or an existing IPLAN, use ../doc-iplan-autopilot/SKILL.md.

Prerequisites

Before writing, read:

1. Template (source of truth): ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml
2. Index template: ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-00_index.TEMPLATE.yaml
3. Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md
4. ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
5. Authoring style: ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

Read the upstream TDD (primary source for the file manifest and test-first order) and the SPEC it derives from. Reference only documents that exist; never invent placeholders like IPLAN-XXX or TBD. Confirm no ID collision: ls docs/08_IPLAN/ 2>/dev/null.

Layer Guidance

Permanent vs Temporary plans (decide first)

Rule of thumb: implements a TDD test contract → permanent; restores intended behavior or fixes a bug → temporary.

Required structure (11 sections — subtype-dependent subset)

The IPLAN is a YAML document with metadata (document_type: iplan-document, layer: 8) followed by the sections matching IPLAN-TEMPLATE.yaml. The required-section set depends on document_control.subtype (CLEANUP-PR-E item 17):

• code_build: sections 1-6 below (document_control, file_manifest, execution_commands, implementation_contracts, session_handoff, traceability).
• deploy: sections 1, 7-11 (document_control, rollback_procedure, smoke_tests, canary_metrics, observability_hooks, runbook_reference) + traceability.
• combined (default): all 11 sections.

Sections 1-6 (code_build set):

1. Document Control — iplan_id (IPLAN-NN), source_spec (@spec: SPEC-NN), status (Draft | In Progress | Completed), version, dates, author, complexity (1=1 file, 5=architectural), estimated_files, session_count.
2. File Manifest — declared creation order, tests before implementation (TDD principle); each file carries order, status, session, verified.
3. Execution Commands — runnable bash for setup, implementation, and validation (the actual bridge to code).
4. Implementation Contracts — Protocol interfaces, exception hierarchies, state machines, data models, DI interfaces live inside the IPLAN. Required only when 3+ files share interfaces; otherwise state "No implementation contracts".
5. Session Handoff — the stateless-executor bridge. sessions[] is a retrospective trail, appended by each session as it ends, so a Draft carries sessions: []. Per appended session: partial_work, blockers, next_session_directive, validation_results.
6. Traceability — required upstream tags (@spec, @tdd), downstream code_paths / test_paths, and code_inventory (audit trail of every file planned/created/modified with session attribution and verified status).

Sections 7-11 (deploy set; required when subtype is deploy or combined):

7. Rollback Procedure — step-by-step rollback with documented reversal per cutover step + verification + reversible flag.
8. Smoke Tests — post-cutover smoke checks with named pass criteria per cutover step.
9. Canary Metrics — explicit thresholds (latency, error rate, saturation) per metric + canary window + action on breach.
10. Observability Hooks — named signals emitted at deploy events
    • dashboard URLs.
11. Runbook Reference — pointer to on-call runbook + new failure-mode entries this deploy adds.

Session handoff protocol

Each stateless session: 1) read session_handoff.sessions for the last state → 2) find the next NOT_STARTED/PARTIAL file in file_manifest → 3) read partial_work if resuming → 4) continue, do not regenerate completed work → 5) update file status → 6) append a session with a next_session_directive. At Draft the trail is sessions: [], so step 1 falls straight through to step 2. Markers: NOT_STARTED | IN_PROGRESS | DONE | PARTIAL.

Document ID and tags

• IPLAN is a DOCUMENT-level artifact — referenced in dash form IPLAN-NN (e.g. @iplan: IPLAN-01). There is no hierarchical dotted element ID for an IPLAN; never write IPLAN.NN.SS.xxxx.
• IPLAN is Layer 8, so it carries the required upstream tags (per the necessary-upstream contract): @spec @tdd. Hierarchical upstreams use the dotted form (@tdd: TDD.01.04.a3c1); document-level upstreams use dash form (@spec: SPEC-01). Upstream BRD/PRD/EARS/BDD/ADR lineage is reachable transitively via SPEC/TDD's own @-tag references — do not emit @brd:/@prd:/@ears:/@bdd:/@adr: on IPLAN elements.
• Removed patterns (do not use): TASK-XXX, TODO-XXX, TI-XXX, ITEM-XXX, and any IPLAN.NN.SS.xxxx hierarchical ID.

Creation Process

1. Determine type — permanent vs temporary (table above).
2. Reserve ID — next free IPLAN-NN (two digits, sequential, never reused); the ID typically matches its SPEC/TDD component. Per-layer independence (CLEANUP-PR-F item 18): pick the next-free number in YOUR layer's index — the upstream's number is NOT your number (doc numbers are per-layer sequential and independent; see framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality).
3. Create the file — permanent: docs/08_IPLAN/IPLAN-NN_{slug}.yaml; temporary: docs/08_IPLAN/tmp/TMP-IPLAN-YYYY-MM-DD_{slug}.yaml.
4. Select subtype (CLEANUP-PR-E item 17) — decide which subtype this IPLAN is and write it to document_control.subtype:
   • code_build: file-manifest + Red/Green/Refactor + execution commands. NO rollback/smoke/canary/observability sections. Use when the IPLAN translates SPEC/TDD to source code only; deployment is a separate plan.
   • deploy: rollback + smoke + canary + observability + runbook sections. NO file-manifest / execution-commands. Use when the IPLAN executes a cutover of code that's already authored.
   • combined (default): both sets required. Use when one IPLAN covers code authoring AND deploy. The auditor reads subtype and dispatches different required-section sets. Missing field defaults to combined.
5. Document Control first, then complete all sections required for the chosen subtype (template marks each section with _required_when_subtype:).
6. Declare the file manifest (code_build / combined only) test-first, every file status: NOT_STARTED.
7. Write execution commands (code_build / combined only) — setup / implementation / validation.
8. Define implementation contracts (code_build / combined only) if 3+ files share interfaces; else state "No implementation contracts".
9. Leave the session handoff empty (code_build / combined only) — session_handoff.sessions: []. A Draft has had no session, so there is nothing to record, and the first executor starts from file_manifest order 1. A session entry written while authoring asserts work that has not happened. Then seed code_inventory with one status: planned entry per file_manifest path (session: null, verified: false). Never leave that inventory empty and never write created into a Draft IPLAN.
10. For deploy subtype only: complete rollback_procedure, smoke_tests, canary_metrics, observability_hooks, runbook_reference (sections 7-11).
11. Register in the index (permanent only) — add to docs/08_IPLAN/IPLAN-00_index.yaml and update metadata.total_plans.
12. Validate (below) and commit the IPLAN and index together.

Validation

This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.

• metadata.layer: 8, document_type: iplan-document.
• Document Control complete (iplan_id, source_spec, status, dates).
• All 6 sections present and non-empty; a Draft's session_handoff carrying sessions: [] satisfies this.
• File Manifest lists tests before implementation; each file has a status marker and verified flag.
• Execution commands cover setup / implementation / validation.
• Implementation Contracts declared (or "No implementation contracts").
• Session Handoff present — sessions: [] at Draft, and every appended session carries a next_session_directive.
• Required upstream tags (@spec @tdd, per necessary-upstream contract) reference existing docs; document ID is IPLAN-NN (no dotted IPLAN element ID).
• code_inventory seeded planned — one entry per file_manifest path, session: null, ready to record created/modified files.
• Permanent plan registered in IPLAN-00_index.yaml; temporary under tmp/.

Error codes (all severity error): XDOC-006 tag format invalid · XDOC-008 broken internal link · XDOC-009 missing traceability section.

Quality gate (blocking): CODE-Ready score ≥ 90/100 with 0 Tier-1 errors before implementation begins. If issues are found, fix and re-check; if unfixable, log for manual review.

Next Skill

IPLAN is the last documentation layer. Proceed to Code: execute the file manifest test-first, updating status/verified, session_handoff, and code_inventory so any later stateless session can resume.

Adaptation

Read .aidoc/profile.yaml; honor only this skill's knobs (section_toggles, glossary). Ignore unknown keys; absent a profile, use framework defaults. Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.

Related Resources

• Template / authoring rules: ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml
• Index template: ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-00_index.TEMPLATE.yaml
• Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md
• ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• Quality gate: ../doc-iplan-audit/SKILL.md · Fixes: ../doc-iplan-fixer/SKILL.md
• Generation pipeline: ../doc-iplan-autopilot/SKILL.md

Quick Reference