Implement Plan Preflight

Implement Plan Preflight

Execute the Preflight phase of the /itp:go workflow. Creates ADR and Design Spec artifacts with proper cross-linking and verification.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• Invoked by /itp:go command during Preflight phase
• User asks to create an ADR for a feature
• User mentions "design spec" or "MADR format"
• Manual preflight verification needed

Preflight Workflow Overview

P.1: Create Feature Branch (if -b flag)
         │
         ▼
P.2: Create ADR File (MADR 4.0)
         │
         ▼
P.3: Create Design Spec (from global plan)
         │
         ▼
P.4: Verify Checkpoint (MANDATORY)

CRITICAL: Do NOT proceed to Phase 1 implementation until ALL preflight steps are complete and verified.

---

Quick Reference

ADR ID Format

YYYY-MM-DD-slug

Example: 2025-12-01-clickhouse-aws-ohlcv-ingestion

File Locations

Cross-Links (MANDATORY)

In ADR header:

**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

In spec.md header:

**ADR**: [Feature Name ADR](/docs/adr/YYYY-MM-DD-slug.md)

---

Execution Steps

Step P.1: Create Feature Branch (Optional)

Only if -b flag specified. See Workflow Steps for details.

Step P.2: Create ADR File

1. Create /docs/adr/$ADR_ID.md 2. Use template from ADR Template 3. Populate frontmatter from session context 4. Select perspectives from Perspectives Taxonomy 5. Use Skill tool to invoke adr-graph-easy-architect for diagrams

Step P.3: Create Design Spec

1. Create folder: mkdir -p docs/design/$ADR_ID 2. Copy global plan: cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md 3. Add ADR backlink to spec header

Step P.4: Verify Checkpoint

Run validator or manual checklist:

uv run scripts/preflight_validator.py $ADR_ID

Checklist (ALL must be true):

• [ ] ADR file exists at /docs/adr/$ADR_ID.md
• [ ] ADR has YAML frontmatter with all 7 required fields
• [ ] ADR has **Design Spec**: link in header
• [ ] DIAGRAM CHECK 1: ADR has Before/After diagram (Context section)
• [ ] DIAGRAM CHECK 2: ADR has Architecture diagram (Architecture section)
• [ ] Design spec exists at /docs/design/$ADR_ID/spec.md
• [ ] Design spec has **ADR**: backlink in header

If any item is missing: Create it now. Do NOT proceed to Phase 1.

---

YAML Frontmatter Quick Reference

---
status: proposed
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-1, Agent-2]
research-method: single-agent
clarification-iterations: N
perspectives: [Perspective1, Perspective2]
---

See ADR Template for full field descriptions.

---

Diagram Requirements (2 DIAGRAMS REQUIRED)

⛔ MANDATORY: Every ADR must include EXACTLY 2 diagrams:

SKILL INVOCATION: Invoke adr-graph-easy-architect skill NOW to create BOTH diagrams.

BLOCKING GATE: Do NOT proceed to design spec until BOTH diagrams are embedded in ADR.

---

Reference Documentation

• ADR Template - Complete MADR 4.0 template
• Perspectives Taxonomy - 11 perspective types
• Workflow Steps - Detailed step-by-step guide

---

Validation Script

# Verify preflight artifacts
uv run scripts/preflight_validator.py <adr-id>

# Example
uv run scripts/preflight_validator.py 2025-12-01-my-feature

---

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Skill: Implement Plan Preflight

ADR Template (MADR 4.0)

Complete template for Architecture Decision Records following MADR 4.0 standards.

YAML Frontmatter (MANDATORY)

Every ADR MUST begin with this frontmatter:

---
status: proposed | accepted | rejected | deprecated | superseded | implemented
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-Perspective-1, Agent-Perspective-2]
research-method: 9-agent-parallel-dctl | single-agent | human-only
clarification-iterations: N
perspectives: [PerspectiveType1, PerspectiveType2]
---

Field Descriptions

---

Required Sections

---

Formatting Rules

1. Blank lines: Required between all content blocks (prevents GitHub rendering issues) 2. Links: Use repository-relative format (/docs/adr/...), never ./ or ../ 3. Design spec link: Include in header: **Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

---

Complete Template

---
status: proposed
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-Perspective-1, Agent-Perspective-2]
research-method: 9-agent-parallel-dctl
clarification-iterations: N
perspectives: [PerspectiveType1, PerspectiveType2]
---

# ADR: [Descriptive Title]

**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

## Context and Problem Statement

[What is the problem? Why does it need a decision?]

### Before/After

<!-- Use Skill tool to invoke adr-graph-easy-architect for Before/After visualization -->

## Research Summary

<!-- Extract from prior session: agent perspectives and material findings -->

| Agent Perspective | Key Finding | Confidence   |
| ----------------- | ----------- | ------------ |
| [Perspective 1]   | [Finding]   | High/Med/Low |
| [Perspective 2]   | [Finding]   | High/Med/Low |

## Decision Log

<!-- Synthesize AskUserQuestion iterations into decision table -->

| Decision Area | Options Evaluated | Chosen | Rationale         |
| ------------- | ----------------- | ------ | ----------------- |
| [Topic 1]     | A, B, C           | A      | [Why A over B, C] |
| [Topic 2]     | X, Y              | Y      | [Why Y over X]    |

### Trade-offs Accepted

| Trade-off | Choice | Accepted Cost                    |
| --------- | ------ | -------------------------------- |
| [X vs Y]  | X      | [What Y offered that we gave up] |

## Decision Drivers

- [Driver 1]
- [Driver 2]

## Considered Options

- **Option A**: [Description]
- **Option B**: [Description]
- **Option C**: [Description] <- Selected

## Decision Outcome

Chosen option: **Option C**, because [rationale from AskUserQuestion iterations + synthesis].

## Synthesis

<!-- Summarize how agent findings were reconciled during prior session -->

**Convergent findings**: [What all perspectives agreed on]
**Divergent findings**: [Where perspectives differed]
**Resolution**: [How user resolved conflicts]

## Consequences

### Positive

- [Benefit 1]

### Negative

- [Trade-off 1]

## Architecture

<!-- Use Skill tool to invoke adr-graph-easy-architect for system architecture diagram -->

## References

- [Related ADR](/docs/adr/YYYY-MM-DD-related.md)
- [Upstream: github.com/org/repo] (if UpstreamIntegration perspective)

---

ADR ID Convention

Format: YYYY-MM-DD-slug

Examples:

• 2025-12-01-clickhouse-aws-ohlcv-ingestion
• 2025-11-28-telegram-bot-network-aware-supervision

File Path: /docs/adr/$ADR_ID.md

---

Slug Word Economy Rule

Each word in the slug MUST convey unique meaning. Avoid redundancy.

Claude Code Ephemeral Context

This document explains the ephemeral nature of Claude Code's Plan Mode artifacts and why the /itp:go workflow exists to capture decisions before they're lost.

Plan File Location & Naming

Claude Code stores plan files in a global directory with randomly-generated names:

Quote from Issue #12707: "The new plan mode... can ONLY use plan files in ~/.claude/plans... Read ../../../.claude/plans/abstract-fluttering-unicorn.md"

Why Random Names?

When asked why it chose glittery_bouncing_feather.md, Claude responded: "it just used a random name." This is not a bug—it's the default behavior. The names are not derived from your task description.

The Overwrite Problem

Plan files are overwritten when:

• You enter Plan Mode for a new task
• A new planning session begins
• Context is compacted and Claude regenerates the plan

This means any decisions made during planning (via AskUserQuestion flows) are lost unless explicitly captured in version-controlled artifacts.

AskUserQuestion Tool

The AskUserQuestion tool is the mechanism Claude uses to clarify requirements during planning. It's not officially documented but widely discussed:

Why This Matters for ADRs

Decisions made via AskUserQuestion flows include:

• Architectural choices (which library, which pattern)
• Trade-off resolutions (performance vs simplicity)
• Scope clarifications (what's in/out of scope)

These decisions live only in the conversation context. When context compacts at ~95% capacity, they're summarized away. The /itp:go workflow captures these decisions in ADRs before they're lost.

References

• GitHub Issue #12707 - Plan files outside ~/.claude/plans
• GitHub Issue #10685 - Plan agent AskUserQuestion behavior
• GitHub Issue #10346 - Missing AskUserQuestion documentation
• Reddit Discussion - Random naming behavior
• egghead.io Tutorial - AskUserQuestion guide
• Anthropic Best Practices - Official guidance

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Skill: Implement Plan Preflight

Perspectives Taxonomy (11 Types)

Use perspectives in ADR frontmatter to describe how the ADR relates to the broader ecosystem.

Taxonomy Table

---

Usage in Frontmatter

---
perspectives: [UpstreamIntegration, BoundaryInterface]
---

Multiple perspectives can apply to a single ADR.

---

Selection Guide

When to Use Each Perspective

ProviderToOtherComponents

• Building shared utilities consumed by multiple projects
• Creating internal libraries or packages
• Designing reusable components

HostPlatformForContributors

• Designing plugin/extension systems
• Building platforms that accept external contributions
• Framework development

StandaloneComponent

• Isolated experiments or proofs of concept
• Self-contained scripts or tools
• No integration with existing systems

UpstreamIntegration

• Consuming third-party APIs (Stripe, AWS, etc.)
• Integrating with external databases
• Using external SDKs or libraries

BoundaryInterface

• Designing public APIs
• Contract-first development
• Adapter patterns between systems

OperationalService

• Monitoring and alerting setup
• Log aggregation configuration
• SRE and DevOps concerns

SecurityBoundary

• Authentication/authorization changes
• Data encryption decisions
• Compliance requirements (GDPR, SOC2)

ProductFeature

• User-facing functionality
• UX/UI decisions
• Feature flags and rollout strategies

EcosystemArtifact

• CLI tools for developers
• Starter templates and boilerplates
• Reference implementations

LifecycleMigration

• Database schema migrations
• API versioning strategies
• Deprecation timelines

OwnershipGovernance

• Team ownership boundaries
• Code review policies
• Process changes

---

Related Repos Reference

When perspective implies external dependencies, reference related repos in ADR body:

## References

- [Upstream: github.com/Eon-Labs/alpha-forge](https://github.com/Eon-Labs/alpha-forge) (UpstreamIntegration)
- [Consumer: github.com/Eon-Labs/trading-bot](https://github.com/Eon-Labs/trading-bot) (ProviderToOtherComponents)

Always use public GitHub URLs, never local paths.

Skill: Implement Plan Preflight

Preflight Workflow Steps

Sequential execution steps for the Preflight phase. Execute in order - do not skip steps.

---

Step P.0: Create Feature Branch (MUST BE FIRST)

Only execute if `-b` or `--branch` flag is specified.

CRITICAL: This step MUST happen BEFORE any file operations (ADR, design spec). Files created before git checkout -b stay on main/master branch.

Generate ADR ID

/usr/bin/env bash << 'WORKFLOW_STEPS_SCRIPT_EOF'
ADR_ID="$(date +%Y-%m-%d)-<slug>"
WORKFLOW_STEPS_SCRIPT_EOF

Detect Primary Branch

/usr/bin/env bash << 'GIT_EOF'
PRIMARY=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$PRIMARY" ] && PRIMARY="main"  # fallback
GIT_EOF

Create Branch

git checkout "$PRIMARY"
git pull origin "$PRIMARY"
git checkout -b "<type>/$ADR_ID"  # e.g., feat/, fix/, refactor/, docs/, chore/

Commit Uncommitted Changes

git add -A
git commit -m "wip: checkpoint before implementing <slug>" || true

Branch Type Selection

---

Step P.1: Create ADR File

Path: /docs/adr/$ADR_ID.md

Actions

1. Create directory if needed: mkdir -p docs/adr 2. Create ADR file using template from ADR Template 3. Populate frontmatter from session context 4. Add Design Spec link in header

Frontmatter Population

Extract from session context:

• decision-maker: User who approved the plan
• consulted: Agent perspectives used in research
• research-method: How research was conducted
• clarification-iterations: Number of AskUserQuestion rounds
• perspectives: Select from Perspectives Taxonomy

Diagram Requirements (2 DIAGRAMS REQUIRED)

⛔ MANDATORY: Every ADR must include EXACTLY 2 diagrams. Do NOT proceed without both.

SKILL INVOCATION (REQUIRED):

1. Invoke Skill tool with `adr-graph-easy-architect` NOW 2. Create Before/After diagram first — embed in ## Context section 3. Create Architecture diagram second — embed in ## Architecture section 4. VERIFY: Search ADR for <!-- graph-easy source: — you must have TWO separate blocks

BLOCKING GATE: Do NOT proceed to Step P.2 until BOTH diagrams are embedded in ADR.

---

Step P.2: Create Design Spec

Create Design Folder

mkdir -p docs/design/$ADR_ID

CRITICAL: Global Plan is Ephemeral

The file at ~/.claude/plans/<adj-verb-noun>.md:

• Replaced when a new plan is created (same session or new)
• Use full path when referencing: ~/.claude/plans/floating-plotting-valiant.md
• After Preflight: spec.md becomes source-of-truth, not the global plan

The source field in spec frontmatter preserves the original filename for traceability, but the file itself may no longer exist.

Create Spec with YAML Frontmatter

1. Copy global plan content:

cp ~/.claude/plans/<adjective-verb-noun>.md docs/design/$ADR_ID/spec.md

2. Prepend YAML frontmatter to the copied spec.md:

---
adr: YYYY-MM-DD-slug
source: ~/.claude/plans/<adjective-verb-noun>.md
implementation-status: in_progress
phase: preflight
last-updated: YYYY-MM-DD
---

3. Add ADR backlink after frontmatter:

**ADR**: [Feature Name ADR](/docs/adr/YYYY-MM-DD-slug.md)

Frontmatter Field Descriptions

Link Format Rule

Use the form [descriptive text](/repo-root-relative/path), never ./ or ../ paths.

---

Step P.3: Verify Checkpoint (MANDATORY)

STOP. Verify artifacts exist before proceeding.

Verification Commands

# Verify ADR exists
[ -f "docs/adr/$ADR_ID.md" ] || { echo "ADR not created: docs/adr/$ADR_ID.md"; exit 1; }

# Verify design spec exists
[ -f "docs/design/$ADR_ID/spec.md" ] || { echo "Design spec not created: docs/design/$ADR_ID/spec.md"; exit 1; }

echo "Preflight complete: ADR and design spec created"

Checklist (ALL must be true)

• [ ] ADR file exists at /docs/adr/$ADR_ID.md
• [ ] ADR has YAML frontmatter with all 7 required fields
• [ ] ADR has status: proposed (initial state)
• [ ] ADR has **Design Spec**: link in header
• [ ] DIAGRAM CHECK 1: ADR has Before/After diagram in Context section (graph-easy block)
• [ ] DIAGRAM CHECK 2: ADR has Architecture diagram in Architecture section (graph-easy block)

⛔ DIAGRAM VERIFICATION: If either diagram is missing, STOP and invoke adr-graph-easy-architect skill. Search for <!-- graph-easy source: — you need TWO separate blocks.

• [ ] Design spec exists at /docs/design/$ADR_ID/spec.md
• [ ] Design spec has YAML frontmatter with all 5 required fields
• [ ] Design spec has implementation-status: in_progress
• [ ] Design spec has phase: preflight
• [ ] Design spec has **ADR**: backlink in header
• [ ] Feature branch created with ADR ID naming (if -b flag specified)

If any item is missing: Create it now. Do NOT proceed to Phase 1.

---

Folder Structure Reference

/docs/
  adr/
    YYYY-MM-DD-slug.md          # ADR file
  design/
    YYYY-MM-DD-slug/            # Design folder (1:1 with ADR)
      spec.md                   # Active implementation spec (SSoT)

Naming Rule: Use exact same YYYY-MM-DD-slug for both ADR and Design folder.

---

Common Errors