---
name: dx-plan
description: Generate an implementation plan with status-tracked steps. Creates implement.md from explain.md + research.md. Uses extended thinking for deep reasoning. Use after requirements are ready (from ADO flow or import).
argument-hint: "[Work Item ID or slug (optional — uses most recent if omitted)]"
model: opus
effort: high
context: fork
allowed-tools: ["read", "edit", "search", "write", "agent"]
---

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.

## Output discipline

You run in a forked context. Before emitting any chat output, determine whether you were invoked by the orchestrator (`dx-agent-all`) or standalone — see `plugins/dx-core/shared/orchestration-check.md`:

```bash
ORCHESTRATED=0
FLAG=".ai/run-context/orchestrating.flag"
if [ -f "$FLAG" ]; then
  AGE=$(( $(date +%s) - $(date -r "$FLAG" +%s) ))
  [ "$AGE" -lt 7200 ] && ORCHESTRATED=1
fi
```

- **If `$ORCHESTRATED == 1`** (orchestrator path): write all canonical artifacts to `$SPEC_DIR/<file>.md` (already documented below) and emit ONLY the `## Return` block to chat.
- **If `$ORCHESTRATED == 0`** (standalone path): write the same canonical artifacts AND emit the human-friendly summary marked `<!-- standalone-only -->` below, followed by the `## Return` block at the very end.

Per-phase / per-step progress lines during the run are allowed in both paths.

Two outputs are always required regardless of path:

1. **`$SPEC_DIR/implement.md`** — the canonical plan, format defined in `.ai/templates/spec/implement.md.template`. This is what the executor reads.
2. **`$SPEC_DIR/plan-thinking.md`** — your reasoning trace: alternatives considered, dependencies analyzed, risks evaluated. Write this BEFORE writing `implement.md`. Maximum 1000 words.

## 1. Locate the Spec Directory

```bash
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 <N> 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:

```bash
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 <N> 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`):

```markdown
## 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>` — <brief approach>."

**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:
```bash
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.

```bash
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 (standalone path only)

<!-- standalone-only — emit only when $ORCHESTRATED == 0 -->

After all phases complete and only when running standalone, emit:

```markdown
## implement.md created

**<Title>** (ADO #<id>)
**Directory:** `.ai/specs/<id>-<slug>/`

### Plan:
- `implement.md` — <count> steps, <count> files referenced
- `plan-thinking.md` — reasoning trace written

### Key Decisions:
<if Key Decisions section exists: list each decision title in one line>
<if no Key Decisions: "(none — straightforward implementation)">

### Risks:
<if Risks section exists: list each risk in one line>
<if no Risks: "(none identified)">

### Next step:
- `/dx-plan-validate` — cross-check plan against requirements
```

When orchestrated (`$ORCHESTRATED == 1`), skip this section entirely and emit only the `## Return` block.

## 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:**
```markdown
### 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.

## Return

This skill runs in a forked context. It MUST end with a `## Return` block per `plugins/dx-core/shared/skill-return-contract.md`.

Examples:

```markdown
## Return
verdict: pass
summary: Generated 4-step plan covering 9 requirements; 3 key decisions documented; 2 risks flagged.
artifacts:
  - .ai/specs/2490722-microsite/implement.md
  - .ai/specs/2490722-microsite/plan-thinking.md
next_action: run /dx-plan-validate
```