dx-plan-resolve - SKILL.md Agent Skill

name: dx-plan-resolve description: Resolve risks and issues flagged by plan-validate. Researches codebase for concrete solutions and updates implement.md steps with fixes. Use after /dx-plan-validate reports warnings or risks. when_to_use: "Use to resolve risks and issues flagged by /dx-plan-validate. Trigger on 'resolve plan issues', 'fix plan risks', 'plan-resolve', or after /dx-plan-validate reports warnings that need addressing." argument-hint: "[Work Item ID or slug (optional — uses most recent if omitted)]" context: fork allowed-tools: ["read", "edit", "search", "write", "agent"]

You resolve risks and issues found during plan validation by researching the codebase for concrete solutions, then updating implement.md with specific fix instructions.

Use ultrathink for this skill — solving risks requires deep reasoning about patterns and codebase specifics.

Output

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:

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 the full report to $SPEC_DIR/resolve-report.md and emit ONLY the ## Return block to chat.
If $ORCHESTRATED == 0 (standalone path): write the same report AND emit the human-friendly summary marked  below, followed by the ## Return block at the very end.

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

This skill writes its full report (per-issue resolution actions and updated implement.md diff summary) to $SPEC_DIR/resolve-report.md.

1. Locate the Spec Directory

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

Read from $SPEC_DIR:

implement.md (required)
research.md (required — for codebase context)
explain.md (for requirement context)

2. Identify Issues to Resolve

Scan implement.md for:

Risks section — anything listed under ## Risks
Blocked steps — steps with **Status:** blocked
Vague instructions — steps that say "may need", "might require", "consider", "TBD" without a concrete solution

Collect each issue as a task to resolve.

If no issues found → print No risks or issues to resolve — plan is ready. and STOP.

3. Research Solutions

For each issue, search the codebase for how the project already solves similar problems.

If .github/instructions/ (or .ai/instructions/) exists, read instruction files relevant to the issue's file types — these provide detailed framework patterns and code examples.

Example: "Dynamic show/hide scoping inside nested repeatable fields"

Search for existing repeatable fields that use show/hide → Grep for the show/hide pattern in config files
Find how they handle scoping → read the matching config and any companion JS
Identify the concrete pattern (scoped CSS classes, row-targeted selectors, etc.)
Formulate a specific solution with exact code/config to add

General approach:

Search for the pattern or keyword in the existing codebase
Find 1-2 working examples of the same technique
Extract the concrete implementation details (class names, config structure, selectors, etc.)
Formulate a specific fix, not a generic recommendation

4. Update implement.md

For each resolved issue:

If the fix belongs in an existing step — append the fix details to that step's **What:** section:

**What:**
<existing instructions>
- **Risk mitigation:** Use unique scoped class `cmp-component__toggle--step{N}` on the
  checkbox field (see `card/config.xml:42` for the same pattern). This scopes
  the show/hide listener to the correct repeatable row.

If the fix needs a new step — insert a step in the correct dependency position:

### Step N: <Descriptive title>
**Status:** pending
**Files:** `path/to/file`, `path/to/other-if-needed`
**What:**
- <concrete instructions with file:line references>
**Why:** Mitigates risk — <one sentence explaining the issue>
**Test:** <specific verification approach>

Update the Risks section — replace vague risk with resolution:

## Risks
- ~~<original risk description>~~ → **Resolved:** <one-line solution> (Step N)

5. Write Resolve Report

Write the following table and summary to $SPEC_DIR/resolve-report.md. Do not print to chat.

## Plan Risks Resolved

| # | Risk/Issue | Resolution | Step Updated |
|---|-----------|------------|--------------|
| 1 | <risk description> | <one-line solution> | Step N |
| 2 | <risk description> | <one-line solution> | New Step M |

**Issues resolved:** <count>
**Steps modified:** <count>
**Steps added:** <count>

Examples

/dx-plan-resolve 2416553 — Reads implement.md risks ("Dynamic show/hide scoping in nested repeatable fields"), searches the codebase for existing repeatable field patterns, finds a working example in card/config.xml, and updates Step 4 with a concrete fix using scoped CSS classes.
/dx-plan-resolve (no argument) — Uses the most recent spec directory. Finds 2 risks and 1 vague step. Resolves all by adding specific file:line references and inserting a new Step 3b for risk mitigation. Updates the Risks section with strikethrough originals and resolution notes.
/dx-plan-resolve 2416553 (no issues) — Reads implement.md, finds no risks, blocked steps, or vague instructions. Prints "No risks or issues to resolve — plan is ready." and stops.

Troubleshooting

"No risks or issues to resolve" Cause: The plan has no Risks section, no blocked steps, and no vague instructions. Fix: This is good — the plan is ready for execution. Run /dx-step-all to proceed.
Resolution references a file that doesn't exist Cause: The codebase search found a pattern in a file that was since moved or deleted. Fix: Run /dx-plan-validate after resolving to verify file existence. Fix any invalid references manually in implement.md.
Step numbering is broken after inserting new steps Cause: A new step was inserted but cross-references to step numbers weren't updated. Fix: Re-run /dx-plan-validate — it checks dependency order and will flag any broken cross-references.

Rules

Research before solving — don't guess at solutions. Find working examples in the codebase first.
Concrete fixes only — every solution must include specific file paths, class names, or code snippets. "Consider using unique selectors" is not a fix. "class='cmp-component__toggle--step2'" is a fix.
Minimal plan changes — prefer adding to existing steps over creating new ones. Only add a new step if the fix is substantial enough to warrant separate execution.
Preserve step numbering — when inserting steps, renumber correctly and update any cross-references.
Don't execute — update the plan only. Execution happens in step-* skills.
One pass — resolve what you can, report what you can't. Don't loop.

Present Summary (standalone path only)

When running standalone, emit the resolve summary to chat:

## Plan Risks Resolved

| # | Risk/Issue | Resolution | Step Updated |
|---|-----------|------------|--------------|
| 1 | <risk description> | <one-line solution> | Step N |
| 2 | <risk description> | <one-line solution> | New Step M |

**Issues resolved:** <count>
**Steps modified:** <count>
**Steps added:** <count>

### Next step:
- `/dx-plan-validate` — re-validate the updated plan

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

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:

## Return
verdict: pass
summary: Resolved 2 risks; updated implement.md (Step 3 split into 3a/3b for clearer commit boundary).
artifacts:
  - .ai/specs/2490722-microsite/resolve-report.md
  - .ai/specs/2490722-microsite/implement.md
next_action: re-run /dx-plan-validate