Doc Iplan

doc-iplan

Purpose

Create Implementation Plans (IPLAN) - Layer 12 artifact in the SDD workflow that converts TASKS into session-based, executable bash command sequences for implementation.

Layer: 12

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6), REQ (Layer 7), IMPL (Layer 8), CTR (Layer 9), SPEC (Layer 10), TASKS (Layer 11)

Downstream Artifacts: Code (Layer 13)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts - skip functionality instead

Before creating IPLAN, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream TASKS: Read task breakdown (PRIMARY SOURCE)
3. Template: ai_dev_flow/IPLAN/IPLAN-TEMPLATE.md
4. Creation Rules: ai_dev_flow/IPLAN/IPLAN_CREATION_RULES.md
5. Validation Rules: ai_dev_flow/IPLAN/IPLAN_VALIDATION_RULES.md
6. Validation Script: ai_dev_flow/scripts/validate_iplan.sh
7. IPLAN Conventions: ID_NAMING_STANDARDS.md (as of 2025-11-26)

When to Use This Skill

Use doc-iplan when:

• Have completed BRD through TASKS (Layers 1-11)
• Ready to convert tasks to executable bash commands
• Preparing for implementation session
• Need step-by-step execution plan
• You are at Layer 12 of the SDD workflow

Reserved ID Exemption (IPLAN-00_*)

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Pattern: IPLAN-00_*.md

Document Types:

• Index documents (IPLAN-00_index.md)
• Traceability matrix templates (IPLAN-00_TRACEABILITY_MATRIX-TEMPLATE.md)
• Glossaries, registries, checklists

Rationale: Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.

Validation Behavior: Skip all checks when filename matches IPLAN-00_* pattern.

IPLAN-Specific Guidance

1. File Naming Convention

Format: IPLAN-NN_{descriptive_slug}.md

Components:

• IPLAN-NN: Sequential 2+ digit ID (e.g., IPLAN-01, IPLAN-02)
• descriptive_slug: Short lowercase description with underscores (e.g., gateway_connection, trade_validation)

Examples:

• IPLAN-01_gateway_connection.md
• IPLAN-02_trade_validation.md
• IPLAN-003_market_data_streaming.md

Filename Validation:

# Validate filename format
filename="IPLAN-01_gateway_connection.md"
if [[ ! $filename =~ ^IPLAN-[0-9]{2,}_[a-z0-9_]+\.md$ ]]; then
  echo "ERROR: Invalid format. Must be IPLAN-NN_{slug}.md"
  exit 1
fi

Tag Format: @iplan: IPLAN-01 (use ID only, not full filename)

1.1 Element ID Format (MANDATORY)

Pattern: IPLAN.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

⚠️ REMOVED PATTERNS - Do NOT use:

• CMD-XXX → Use IPLAN.NN.19.SS
• STEP-XXX → Use IPLAN.NN.31.SS

Reference: ID_NAMING_STANDARDS.md — Cross-Reference Link Format

1.2 Required Frontmatter Structure

CRITICAL: Every IPLAN file MUST include this frontmatter structure with the tags: section:

---
tags:
  - implementation-plan
  - layer-12-artifact
  - active
name: "IPLAN-NN: [Descriptive Task/Feature Name]"
layer: 12
artifact_type: IPLAN
parent_tasks: TASKS-NN
dependencies: []
status: ready
created: YYYY-MM-DD
estimated_effort_hours: NN
# Layer 12 Cumulative Traceability Tags
traceability:
  brd: "BRD-NN" or null
  prd: "PRD-NN" or null
  ears: "EARS-NN" or null
  bdd: "BDD-NN" or null
  adr: "ADR-NN" or null
  sys: "SYS-NN"
  req: "REQ-NN"
  spec: "SPEC-NN"
  tasks: "TASKS-NN"
---

MANDATORY TAGS:

• implementation-plan - Identifies document type
• layer-12-artifact - REQUIRED for validation (validation will FAIL without this)
• active - Document status

Validation will reject files missing layer-12-artifact tag.

2. Session-Based Execution Plan

Purpose: Convert TASKS into executable bash command sequences

Format:

## Execution Plan

### Session 1: Project Setup (Estimated: 1.5 hours)

**Tasks**: IPLAN.01.31.01, IPLAN.01.31.02

**Commands**:
```bash
# IPLAN.01.19.01: Initialize Project Structure
mkdir -p src/controllers src/services src/repositories src/models
mkdir -p tests/unit tests/integration
touch src/controllers/data_validation_controller.py
touch src/services/data_validator.py
touch src/repositories/data_repository.py
touch src/models/data_request.py
touch src/__init__.py

# Verify structure created
ls -R src/

# IPLAN.01.19.02: Set Up Development Environment
cat > requirements.txt <<EOF
fastapi==0.104.1
pydantic==2.5.0
sqlalchemy==2.0.23
pytest==7.4.3
pytest-cov==4.1.0
EOF

cat > pyproject.toml <<EOF
[project]
name = "data-validator"
version = "1.0.0"
requires-python = ">=3.11"
EOF

# Install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Verify installation
pip list | grep fastapi

Validation:

# Verify all files created
test -f src/controllers/data_validation_controller.py && echo "✓ Controller file exists"
test -f src/services/data_validator.py && echo "✓ Service file exists"

# Verify dependencies installed
python -c "import fastapi; print(f'✓ FastAPI {fastapi.__version__} installed')"

Rollback (if needed):

rm -rf src/ tests/ requirements.txt pyproject.toml .venv

### 3. Required Sections

**Document Control** (MANDATORY - First section before all numbered sections)

**Core Sections**:
1. **Overview**: Session-based execution summary
2. **Prerequisites**: What must be ready before starting
3. **Execution Plan**: Session-by-session commands (primary content)
4. **Validation Commands**: How to verify each session
5. **Rollback Procedures**: How to undo if needed
6. **Notes and Warnings**: Important considerations
7. **Traceability**: Section 7 format with cumulative tags

### 4. Session Organization

**Typical Sessions**:

1. **Session 1: Project Setup** (infrastructure)
2. **Session 2: Data Models** (schemas, Pydantic models)
3. **Session 3: Business Logic** (services, algorithms)
4. **Session 4: API Layer** (controllers, routing)
5. **Session 5: Error Handling** (middleware, error codes)
6. **Session 6: Configuration** (env vars, settings)
7. **Session 7: Testing** (unit, integration tests)
8. **Session 8: Deployment** (Docker, CI/CD)

**Each Session Includes**:
- Tasks covered (IPLAN element IDs)
- Bash commands (executable)
- Validation commands
- Rollback procedure

### 5. Command Format

**Bash Commands**:
- Must be executable (copy-paste ready)
- Include comments explaining each step
- Use heredocs for multi-line files
- Include error checking

**Example**:
```bash
# Create FastAPI controller
cat > src/controllers/data_validation_controller.py <<'EOF'
from fastapi import APIRouter, HTTPException
from src.models.data_request import DataRequest, ValidationResponse
from src.services.data_validator import validate_data_request

router = APIRouter()

@router.post("/api/v1/data/validate", response_model=ValidationResponse)
async def validate_data(record: DataRequest):
    """Validate data record endpoint"""
    try:
        result = await validate_data_request(record)
        return result
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
EOF

# Verify file created and syntax valid
test -f src/controllers/data_validation_controller.py || exit 1
python -m py_compile src/controllers/data_validation_controller.py

6. Validation Commands

After Each Session: Provide commands to verify success

Format:

**Validation**:
```bash
# Verify files exist
test -f src/controllers/data_validation_controller.py && echo "✓ Controller created"
test -f src/services/data_validator.py && echo "✓ Service created"

# Verify syntax valid
python -m py_compile src/controllers/*.py
python -m py_compile src/services/*.py

# Run unit tests
pytest tests/unit/ -v

# Check test coverage
pytest tests/unit/ --cov=src --cov-report=term-missing

### 7. Rollback Procedures

**For Each Session**: Provide commands to undo changes

**Format**:
```markdown
**Rollback** (if needed):
```bash
# Remove created files
rm -f src/controllers/data_validation_controller.py
rm -f src/services/data_validator.py

# Reset git (if committed)
git reset --hard HEAD~1

## Tag Format Convention (By Design)

The SDD framework uses two distinct notation systems for cross-references:

| Notation | Format        | Artifacts                               | Purpose                                                             |
|----------|---------------|----------------------------------------|---------------------------------------------------------------------|
| Dash     | TYPE-NN      | ADR, SPEC, CTR, IPLAN, ICON            | Technical artifacts - references to files/documents                 |
| Dot      | TYPE.NN.TT.SS | BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS | Hierarchical artifacts - references to elements inside documents |

**Key Distinction**:
- `@adr: ADR-033` → Points to the document `ADR-033_risk_limit_enforcement.md`
- `@brd: BRD.17.01.01` → Points to element 01.01 inside document `BRD-017.md`

## Unified Element ID Format (MANDATORY)

**For hierarchical requirements (BRD, PRD, EARS, BDD, SYS, REQ)**:
- **Always use**: `TYPE.NN.TT.SS` (dot separator, 4-segment unified format)
- **Never use**: `TYPE-NN:NNN` (colon separator - DEPRECATED)
- **Never use**: `TYPE.NN.TT` (3-segment format - DEPRECATED)

**Element Type Codes** (use in cumulative tags):

| Artifact | Element Type | Code | Example |
|----------|--------------|------|---------|
| BRD | Business Requirement | 01 | BRD.01.01.03 |
| PRD | Product Feature | 07 | PRD.01.07.02 |
| EARS | Statement | 25 | EARS.01.25.01 |
| BDD | Scenario | 14 | BDD.01.14.01 |
| SYS | System Requirement | 26 | SYS.01.26.01 |
| REQ | Atomic Requirement | 27 | REQ.01.27.01 |
| IMPL | Implementation Phase | 29 | IMPL.01.29.01 |
| TASKS | Task | 18 | TASKS.01.18.01 |
| IPLAN | Command | 19 | IPLAN.01.19.01 |
| IPLAN | Plan Step | 31 | IPLAN.01.31.01 |


## Cumulative Tagging Requirements

**Layer 12 (IPLAN)**: Must include tags from Layers 1-11

**Tag Count**: 9-11 tags (minimum 9, maximum 11)

**Minimum (IMPL and CTR skipped)**:
```markdown
## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 12):
```markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@spec: SPEC-01
@tasks: TASKS.01.18.01

Maximum (IMPL and CTR included):

@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@impl: IMPL.01.29.01
@ctr: CTR-01
@spec: SPEC-01
@tasks: TASKS.01.18.01

Upstream/Downstream Artifacts

Upstream Sources:

• BRD (Layer 1) - Business requirements
• PRD (Layer 2) - Product features
• EARS (Layer 3) - Formal requirements
• BDD (Layer 4) - Test scenarios
• ADR (Layer 5) - Architecture decisions
• SYS (Layer 6) - System requirements
• REQ (Layer 7) - Atomic requirements
• IMPL (Layer 8) - Implementation approach (optional)
• CTR (Layer 9) - Data contracts (optional)
• SPEC (Layer 10) - Technical specifications
• TASKS (Layer 11) - Task breakdown (PRIMARY SOURCE)

Downstream Artifacts:

• Code (Layer 13) - Implementation

Same-Type Document Relationships (conditional):

• @related-iplan: IPLAN-NN - IPLANs sharing session context
• @depends-iplan: IPLAN-NN - IPLAN that must be completed first

Creation Process

Step 1: Read Upstream TASKS

Read TASKS (Layer 11) - task breakdown to convert to commands.

Step 2: Reserve ID Number

Check docs/IPLAN/ for next available ID number.

ID Numbering Convention: Start with 2 digits and expand only as needed.

• ✅ Correct: IPLAN-01, IPLAN-99, IPLAN-102
• ❌ Incorrect: IPLAN-001, IPLAN-009 (extra leading zero not required)

Step 3: Create IPLAN File

Location: docs/IPLAN/IPLAN-NN_{slug}.md (template available at ai_dev_flow/IPLAN/)

Example: docs/IPLAN/IPLAN-01_data_validation.md

Step 4: Fill Document Control Section

Complete metadata and Document Revision History table.

Step 5: Write Overview

Summarize session-based execution approach.

Step 6: Define Prerequisites

List what must be ready before starting (database, credentials, etc.).

Step 7: Create Session-by-Session Execution Plan

For each session:

1. List tasks covered (IPLAN element IDs)
2. Write executable bash commands
3. Add comments explaining each step
4. Include error checking

Step 8: Add Validation Commands

For each session, provide commands to verify success.

Step 9: Add Rollback Procedures

For each session, provide commands to undo changes.

Step 10: Document Notes and Warnings

Important considerations, potential issues.

Step 11: Add Cumulative Tags

Include all 9-11 upstream tags (@brd through @tasks).

Step 12: Create/Update Traceability Matrix

MANDATORY: Update docs/IPLAN/IPLAN-00_TRACEABILITY_MATRIX.md

Step 13: Validate IPLAN

ai_dev_flow/scripts/validate_iplan.sh docs/IPLAN/IPLAN-01_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact IPLAN-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,ctr,spec,tasks --strict

# Test bash commands (dry-run)
bash -n docs/IPLAN/IPLAN-01_*.md  # syntax check

Step 14: Commit Changes

Commit IPLAN file and traceability matrix.

Validation

Validation Checks Summary

Automated Validation

# Quality gates
scripts/validate_quality_gates.sh docs/IPLAN/IPLAN-01_*.md

# IPLAN format validation
ai_dev_flow/scripts/validate_iplan.sh docs/IPLAN/IPLAN-01_*.md

# Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --artifact IPLAN-01 \
  --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,ctr,spec,tasks \
  --strict

# Bash syntax check
bash -n docs/IPLAN/IPLAN-01_*.md

Manual Checklist

• File naming follows IPLAN-NN_{slug}.md format
• Document Control section at top
• Overview explains session-based approach
• Prerequisites listed (database, credentials, etc.)
• Execution Plan organized into sessions
• Each session lists covered element IDs (IPLAN.NN.TT.SS format)
• Bash commands are executable (copy-paste ready)
• Comments explain each command
• Validation commands provided for each session
• Rollback procedures provided for each session
• Notes and Warnings documented
• Cumulative tags: @brd through @tasks (9-11 tags) included
• Traceability matrix updated
• Bash syntax valid (bash -n passes)

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Common Pitfalls

1. Non-executable commands: Commands must be copy-paste ready
2. Missing validation: Each session needs validation commands
3. No rollback: Must provide undo procedures
4. Wrong file naming: Must use IPLAN-NN_{slug}.md format
5. Missing cumulative tags: Layer 12 must include all 9-11 upstream tags
6. No error checking: Commands should check for errors
7. Relative paths: Use absolute paths always (not ../src)
8. Missing layer-12-artifact tag: Validation will FAIL without this tag
9. Legacy element IDs: Use IPLAN.NN.19.SS not CMD-XXX; use IPLAN.NN.31.SS not STEP-XXX

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

Automatic Validation Loop

LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

Validation Command

# Per-document validation (Phase 1)
python ai_dev_flow/scripts/validate_cross_document.py --document docs/IPLAN/IPLAN-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all IPLAN documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer IPLAN --auto-fix

Layer-Specific Upstream Requirements

Auto-Fix Actions (No Confirmation Required)

Validation Codes Reference

Quality Gate

Blocking: YES - Cannot proceed to next document until Phase 1 validation passes with 0 errors.

Next Skill

After creating IPLAN, proceed to:

Code Implementation (Layer 13)

Execute the IPLAN session-by-session to implement the code.

Reference Documents

For supplementary documentation related to IPLAN artifacts:

• Format: IPLAN-REF-NNN_{slug}.md
• Skill: Use doc-ref skill
• Validation: Minimal (non-blocking)
• Examples: Session execution guides, environment setup guides

Related Resources

• Template: ai_dev_flow/IPLAN/IPLAN-TEMPLATE.md (primary authority)
• IPLAN Creation Rules: ai_dev_flow/IPLAN/IPLAN_CREATION_RULES.md
• IPLAN Validation Rules: ai_dev_flow/IPLAN/IPLAN_VALIDATION_RULES.md
• IPLAN README: ai_dev_flow/IPLAN/README.md
• ID Naming Standards: ai_dev_flow/ID_NAMING_STANDARDS.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Quick Reference

IPLAN Purpose: Convert TASKS into session-based bash command execution plans

Layer: 12

Element ID Format: IPLAN.NN.TT.SS

• Command = 19
• Plan Step = 31

Removed Patterns: CMD-XXX, STEP-XXX

Tags Required: @brd through @tasks (9-11 tags)

Format: Session-based execution plan with bash commands

IPLAN-Ready Score: ≥90% target for implementation readiness

File Naming: IPLAN-NN_{slug}.md

Tag Format: @iplan: IPLAN-01 (use ID only, not full filename)

Key Sections:

• Prerequisites
• Execution Plan (session-by-session)
• Validation Commands
• Rollback Procedures
• Notes and Warnings

Session Structure:

• Tasks covered (IPLAN element IDs)
• Executable bash commands
• Validation commands
• Rollback procedure

Next: Code Implementation (Layer 13)