dx-plan

You read the spec documents and use extended thinking to generate implement.md — a concrete, step-by-step development plan with status tracking for automated execution.

Use ultrathink for this skill — implementation planning benefits from deep reasoning about dependencies, ordering, and edge cases.

1. Locate the Spec Directory

SPEC_DIR=$(bash .ai/lib/dx-common.sh find-spec-dir $ARGUMENTS)

If the script exits with error, ask the user for the work item ID or slug.

Read these files from $SPEC_DIR (in order of importance):

• research.md — codebase findings (required for a good plan)
• explain.md — distilled requirements
• raw-story.md — original story for reference (may not exist for non-ADO flows)

If research.md doesn't exist, warn the user: "No research.md found — run /dx-req first for a better plan. Proceeding with explain.md only."

Provenance Check on Inputs

Read shared/provenance-schema.md for the schema definition.

After reading each input file, parse its YAML frontmatter provenance: block (if present). Evaluate input quality:

1. research.md provenance:

   • If confidence: low → warn: "⚠ research.md has low confidence (degraded mode or incomplete data). Plan quality may be affected — consider re-running /dx-req with better search hints."
   • If confidence: medium or high → no warning needed
   • If no provenance block → informational: "ℹ research.md has no provenance metadata (pre-migration file). Confidence unknown."
   • If model: haiku → note: "ℹ research.md was produced at Haiku tier. For complex features, consider re-running /dx-req at higher tier."

2. explain.md provenance:

   • If confidence: low → warn: "⚠ explain.md has low confidence. Requirements may be incomplete — verify with the original ticket."
   • If no provenance block → skip (informational only, don't block)

Confidence propagation: Use the lowest confidence from input files as the ceiling for implement.md provenance. If research.md is low, implement.md cannot be higher than low — regardless of planning quality, the plan is only as reliable as its inputs.

Also check for Figma prototype files (from /dx-figma-prototype):

• figma-conventions.md — discovered project conventions (design tokens, naming, patterns)
• prototype/index.html — standalone HTML prototype
• prototype/styles.css — CSS with project token mappings
• figma-extract.md — raw Figma extraction data

If prototype files exist, the plan MUST reference them. Implementation steps should adapt the prototype into project-native code rather than building from scratch.

Component Reuse Map: If figma-conventions.md contains a ### Component Reuse Map section, the plan MUST respect it:

• Components marked Reuse as-is → plan step says "Use existing <component> at <path>" — NO new file creation
• Components marked Extend → plan step modifies the existing component file, adding the identified variant
• Components marked Compose → plan step assembles from listed existing components — NO new wrapper when composition suffices
• Components marked Create new → plan step creates a new component following the nearest existing pattern
• Atomic components (button, image, icon, link, input, badge) should ALWAYS be reused. A plan step that recreates an existing atomic component is a plan defect.

Hub Mode Check

Read shared/hub-dispatch.md for hub detection logic.

If hub mode is active (hub.enabled: true AND cwd is .hub/):

1. Read research.md → ## Cross-Repo Scope for per-repo scope
2. If cross-repo scope detected: a. Resolve target repos from config b. For each repo, dispatch planning: cd <repo.path> && claude -p "/dx-plan <ticket-id>" --output-format json --allowedTools "Bash,Read,Edit,Write,Glob,Grep" --permission-mode bypassPermissions c. Each repo generates its own implement.md locally d. Collect and summarize: "Plans generated in repos"
3. Write state files
4. STOP — do not continue with local planning

If hub mode is not active: continue with normal flow below.

2. Check Existing Output

1. Check if implement.md exists in the spec directory
2. If it exists, read its content
3. Check staleness indicators:
   • Does the title in implement.md match the current spec?
   • Does the step count and files referenced align with current research.md?
   • Have research.md or explain.md changed since implement.md was generated?
4. If implement.md is current → print implement.md already up to date — skipping and STOP
5. If inputs changed or plan looks stale → print implement.md exists but is outdated — regenerating and continue
6. If not found → continue normally (first run)

3. Plan Format Rules

If .ai/rules/plan-format.md exists (project override), read and follow it. Otherwise read the plugin's rules/plan-format.md.

If .github/instructions/ (or .ai/instructions/) exists, read instruction files relevant to the file types in this spec — these provide detailed code examples and framework patterns for generating concrete implementation steps.

Design Exploration & Decision Capture

If this is a complex feature with multiple valid approaches, check if superpowers:brainstorming is available and invoke it to explore the design space before planning.

Fallback (if superpowers not installed): Before generating the plan, briefly consider:

• Are there 2-3 valid approaches? Document the chosen one and why.
• What are the key tradeoffs (performance vs simplicity, reuse vs custom)?
• Are there unknowns that need spiking first?

If a brainstorming spec already exists in docs/superpowers/specs/, read it for design context.

Decision capture: Any non-obvious design decision surfaced during exploration MUST be recorded in the ## Key Decisions section of implement.md. This includes:

• Architecture choices (extend existing component vs create new)
• Pattern selection (which existing pattern to follow when multiple exist)
• Scope tradeoffs (what was deliberately excluded and why)
• Technology choices (when research.md shows multiple viable approaches)

If the change is trivial (single-file edit, config-only, straightforward bug fix) or every decision is obvious from requirements, omit the Key Decisions section.

Cross-Ticket Pattern Lookup

Check if .ai/graph/nodes/patterns/ exists and contains YAML files:

find .ai/graph/nodes/patterns/ -name "*.yaml" -type f 2>/dev/null

If pattern files exist, read shared/pattern-schema.md for the schema, then read each pattern file. Match patterns against the current ticket by:

1. Tag matching — compare pattern tags against component names, file types, and architectural concepts from research.md
2. File matching — compare pattern files against files listed in research.md's ## Files Inventory or ## Key Findings
3. Decision matching — compare pattern description against the current ticket's requirements in explain.md

If relevant patterns found:

• Print: "Found relevant patterns from previous tickets"
• Factor them into design decisions — if a pattern covers this ticket's approach, reference it rather than re-deriving the approach
• Include a ## Relevant Patterns section in implement.md (before ## Steps):

## Relevant Patterns

| Pattern | Confidence | Tickets | Relevance |
|---------|-----------|---------|-----------|
| <title> | <confidence> | <count> | <why it matches> |

> **<pattern-id>:** <approach summary from pattern>. (from <ticket list>)

• When a plan step relates to a known pattern, reference it in the step's **What:** section: "Follow established pattern <pattern-id> — ."

If no patterns found (directory empty or doesn't exist): continue without the section. This is normal for new projects or early tickets.

AEM Component Intelligence Rules

If research.md contains an ## AEM Component Intelligence section, apply these three rules during step generation:

Rule 1: Variant Completeness

When a step modifies a component, check AEM Component Intelligence for variants:

• Variants in this repo → include in the SAME step as additional files to modify (same change, different file path)
• Variants in other repos → add a NOTE at the bottom of the step: "⚠ Variant <name> in <repo> may need the same change. Verify in a separate session."

Every step that touches a component MUST account for all known variants. Missing a variant is a plan defect.

Rule 2: Field Semantic Awareness

When a step references an AEM dialog field (e.g., for aria-label, display text, image alt), verify the field's semantic meaning from AEM Component Intelligence:

• Check the field's Label and Sample Authored Values
• If the plan's intended use doesn't match the field's actual semantic meaning → flag in the step with the correct field and explanation
• Example: plan says "use heading for product name" but AEM shows heading Label="Product Price", Value="$29.99" → step must note: "Use text (Product Name), NOT heading (Product Price)"

Rule 3: Null Content Guard

When a step renders a dialog field value in the UI (link text, label, display content):

• Check AEM Component Intelligence for that field's authored values across pages
• If ANY page shows the field as empty ("(empty)" or blank) → add a sub-task to the step: "Guard: AEM shows <field> is empty on <page>. Wrap rendering in conditional to prevent empty elements (empty <a>, <span>, etc.)."

These rules are technology-agnostic — they specify WHAT to guard, not HOW. The project's .claude/rules/ files provide syntax-specific patterns (HTL conditionals, HBS {{#if}}, etc.).

Cross-Repo Step Markers

If research.md contains a ## Cross-Repo Scope section with Scope: Multi-repo:

1. Read repo names from the Cross-Repo Scope section
2. Prefix each step title with a repo tag: [This repo], [{Repo-Name}]
3. Group steps by repo: all backend-repo steps first, then this-repo steps
4. Between repo groups, add a separator note:

Steps tagged [{Backend-Repo}] must be implemented in that repo. Deploy before starting [This repo] steps.

5. The **Other repos required:** line at plan completion lists all non-current repos from the scope section

Example:

Step 1: Add dialog field [{Backend-Repo}]

Files: ui.apps/.../component/_cq_dialog/.content.xml What: Add newField to dialog Verification: Field appears in dialog XML

Steps tagged [{Backend-Repo}] must be implemented in that repo. Deploy before starting [This repo] steps.

Step 2: Consume new field [This repo]

Files: ui.frontend/src/.../component.js What: Read newField from data model Verification: Field renders on page

If research.md has no Cross-Repo Scope section or scope is "This repo only", do not add repo tags.

4. Generate implement.md

Analyze all inputs and write implement.md in the same spec directory.

Include the provenance frontmatter block at the top of implement.md, before the # Implementation Plan: heading. Use agent: dx-plan. Set confidence using the propagation rule from the Provenance Check step: the lowest input confidence is the ceiling, then apply the standard downgrade rule (no research.md → low). Default is medium when all inputs have medium or high confidence.

Read .ai/templates/spec/implement.md.template and follow that structure exactly. Key rules:

• Every step MUST have **Status:** pending (initial state)
• Steps are ordered by implementation dependency
• Be specific about property names, types, default values, file paths with line numbers
• Include code snippets when helpful
• Key Decisions section: record non-obvious choices with alternatives and rationale. OMIT for trivial changes.
• Risks section: only REAL technical risks. OMIT if none.

5. Write Decision Nodes

If implement.md contains a ## Key Decisions section (i.e., non-trivial decisions were made), externalize each decision as a structured YAML file.

Read shared/decision-schema.md for the schema definition.

When to write

• If the Key Decisions section was omitted (trivial change) → skip this step entirely
• If Key Decisions section exists → write one YAML file per decision

How to write

1. Create the directory if needed:

mkdir -p .ai/graph/nodes/decisions

2. For each decision in the ## Key Decisions section, write a YAML file to .ai/graph/nodes/decisions/<ticket>-<slug>.yaml:

   • <ticket> is the work item ID (from spec directory name)
   • <slug> is a kebab-case summary of the decision title (e.g., extend-layout-dropdown)
   • Map the markdown fields to YAML: **Chosen:** → chosen:, **Why:** → why:, **Alternatives considered:** → alternatives:, **Affects steps:** → affects_steps:
   • Set confidence from the same propagation logic used for implement.md provenance
   • Set trust_tier: shared, status: active
   • Populate tags from technology names, component types, and architectural concepts mentioned in the decision
   • Populate lineage with references to the input spec files that informed this decision (e.g., requirement-<ticket>-raw, research-<ticket>)
   • Populate files from files mentioned in the decision or the affected steps

3. If decision YAML files already exist for this ticket (re-planning), overwrite them. Set status: superseded on any old decision files that are no longer in the new plan's Key Decisions section.

Content parity

The YAML files contain the same information as the markdown Key Decisions section — they are the structured counterpart for machine consumption. Do not add or remove decisions between the two formats.

Write edges

After writing decision nodes, write (or update) the per-ticket edge file. Read shared/edge-schema.md for the schema.

mkdir -p .ai/graph/edges

Write .ai/graph/edges/<ticket>.yaml with edges derived from the planning context:

1. informed edges — for each decision node, add edges from requirement-<ticket>-raw and research-<ticket> to the decision ID (these come from the decision's lineage field)
2. implemented-as edges — for each decision node, add edges from the decision ID to step-<ticket>-<N> for each step in affects_steps
3. reuses edges — if a plan step references a pattern from ## Relevant Patterns, add an edge from step-<ticket>-<N> to the pattern ID

If the edge file already exists (re-planning), replace all edges where agent: dx-plan but preserve edges from other agents (e.g., dx-step-verify).

6. Status Tracking

Every step MUST have a **Status:** line with one of:

• pending — not yet started (initial state)
• in-progress — currently being worked on
• done — completed and verified
• blocked — cannot proceed, with reason

The step-* skills update these statuses as they execute.

7. Planning Principles

• Reuse before create — if research.md's "Existing Implementation Check" shows existing code covers a requirement (✅ or ⚡), the step MUST reuse/extend that code. Never create a new utility, helper, service, or component when an existing one can be extended. If research.md doesn't have this section, search the codebase yourself before planning a "Create new" step.
• Every step references specific files and line numbers from research.md
• Steps are ordered by dependency — what must be done first for the next step to work
• Pattern references are concrete — "follow the pattern in ModelName.java:45"
• Each step has a Test line — specific test command or compile check
• Prototype-first — if prototype/ exists, implementation steps adapt it into the project's build system. The step should reference specific prototype files:
  • "Adapt HTML structure from prototype/index.html into the HBS template"
  • "Migrate CSS from prototype/styles.css into component SCSS, replacing flat values with project variables/mixins"
  • "Compare rendered output against prototype/figma-reference.png"
  • The prototype uses the project's naming conventions, so class names and structure should carry over with minimal changes.
• Conventions as reference — if figma-conventions.md exists, implementation steps should cite it for specific variable names, mixin usage, and naming patterns. E.g., "Use @include media-breakpoint-up(lg) for desktop breakpoint (see figma-conventions.md)."
• No time estimates
• Scale to complexity — simple change = 3-4 steps, complex feature = 10+

8. Present Summary

## implement.md created

**<Title>**
- Steps: <count> (all pending)
- Key decisions: <count or "none"> (decision nodes written to `.ai/graph/nodes/decisions/`)
- Files to modify: <count>
- Files to create: <count>
- Tests planned: <count> unit, manual verification included
- Risks identified: <count or "none">

### Next steps:
- `/dx-plan-validate` — verify plan covers all requirements
- `/dx-step` — execute first step
- `/dx-step-all` — execute all steps autonomously

Examples

Standard planning flow

/dx-plan 2416553

Reads .ai/specs/2416553-add-layout-switcher/explain.md and research.md, generates implement.md with 6 steps covering model changes, dialog updates, HTL template, JS logic, SCSS, and tests. All steps start as pending.

Re-run after research update

/dx-plan 2416553

Detects that research.md has changed since implement.md was generated. Prints "implement.md exists but is outdated — regenerating" and creates a fresh plan.

Without research (degraded mode)

/dx-plan 2416553

If research.md doesn't exist, warns "No research.md found — run /dx-req first for a better plan" and generates from explain.md only. Plan will lack specific file paths and line numbers.

Troubleshooting

"No spec directory found"

Cause: No .ai/specs/ directory matches the given ID or slug. Fix: Run /dx-req <id> first to create the spec directory, or check the ID is correct.

Plan has vague steps without file paths

Cause: research.md is missing or has thin results. Fix: Run /dx-req <id> with search hints to get better codebase findings, then re-run /dx-plan.

Plan creates new utilities instead of reusing existing ones

Cause: research.md didn't find existing utilities, or the "Existing Implementation Check" section is missing. Fix: Run /dx-req <id> again — it may find more with different search terms. Or manually add findings to research.md before re-planning.

Decision Tree: Step Granularity

Change set identified →
├── All files share one concern (same component) → 1 step (up to ~8 files)
├── Files split across concerns (FE + BE + test) → split by concern
├── >8 files in one concern → split by component boundary
└── Test files →
    ├── Unit tests for single component → include in component step
    └── Integration tests spanning components → separate step

Decision Examples

Reuse vs Create New

Scenario: Plan step says "add form validation for phone numbers" Discovery: src/core/scripts/libs/forms.js has validateField() with email, text, number patterns Decision: EXTEND — add phone regex to existing validateField(). Don't create new util. Why: Existing utility covers >70% of need. Only a new regex pattern is needed.

Key Decision entry:

### Form validation approach
**Chosen:** Extend existing `validateField()` in `forms.js`
**Why:** Covers >70% of need — only a new regex pattern is required
**Alternatives considered:**
- New `phoneValidator.js` utility — rejected because existing utility handles all other field types; a separate file fragments validation logic
**Affects steps:** 2

When to Create New

Scenario: Need color-coded severity badge component for QA dashboard Discovery: Closest match is HighlightBox (callout alert) — wrong abstraction (alert vs badge) Decision: CREATE — no existing component serves this purpose Why: Repurposing HighlightBox would fight its design. Clean creation is simpler.

Step Granularity

Scenario: Change touches hero.js (FE), HeroModel.java (BE), hero.html (template), hero-test.js (test) Decision: 2 steps — Step 1: BE (HeroModel.java), Step 2: FE (hero.js + hero.html + hero-test.js) Why: BE and FE are independent concerns. FE files change together (same concern).

Pre-Presentation Validation

Before presenting the generated plan:

1. Re-read explain.md — list every requirement
2. For each requirement, verify ≥1 plan step addresses it
3. For each plan step, verify it traces to a requirement
4. Flag gaps: "Requirement #{N} has no corresponding plan step"
5. Flag extras: "Step #{N} does not trace to any requirement"

Success Criteria

• implement.md exists in spec directory
• Every step has **Status:** pending
• Every step lists ≥1 file in **Files:**
• No duplicate step numbers
• Steps ordered by dependency (no forward references)

Anti-Rationalization

Common excuses for weak planning — and why they're wrong:

False Logic	Reality Check
"I'll figure it out as I code"	Coding without a plan produces twice the rework. Plan first, code once.
"The requirements are obvious"	"Obvious" requirements produce the most bugs. Write them down explicitly.
"We don't need tests in the plan"	Every step needs a verification command. Untested steps are unverified steps.
"I'll create a new utility for this"	Search first. 80% of the time an existing utility covers the need.
"This is too simple for a plan"	If it touches >2 files, it needs a plan. "Simple" changes cause unexpected ripple effects.
"I'll plan all the edge cases later"	Edge cases discovered during coding cause scope creep and rework. Surface them now.

Risk-First Slicing

When ordering steps, tackle highest-uncertainty pieces first:

• Unknown APIs or integrations → spike early, fail fast
• Core data model changes → establish early, everything depends on them
• Complex algorithms → prove feasibility before building UI around them
• Simple UI wiring → leave for last, lowest risk

Change sizing: Aim for steps that produce ~100 lines of diff each. Smaller is reviewable; larger hides problems.

Rules

• Grounded in research — every file reference must come from research.md findings
• No duplication — never plan to create something that already exists in the codebase. If research.md identifies existing utilities, helpers, services, or patterns, the plan MUST reuse them. A step that creates a new helper when an existing one covers the need is a plan defect.
• Concrete over abstract — property names, types, default values, paths
• Dependency-ordered — steps in the order they should be implemented
• No invented requirements — only implements what explain.md says
• Domain-aware — use correct terminology for the project's technology stack
• Status on every step — **Status:** pending is mandatory
• Current repo only — only plan steps for files that exist in this repo. If research.md has a "Cross-Repo Scope" section, add the **Other repos required:** header line but do NOT create steps for those repos. The developer runs the workflow in each repo separately.