dx-plan-resolve

Isolation check. This skill is meant to run in its own context (context: fork). If you can see the user's messages from before this skill was invoked, you are running inline (Copilot CLI ignores context: fork): do not run the steps below yourself. Start one subagent with your task/subagent tool, give it only this instruction — "Invoke the dx-core:dx-plan-resolve skill with these arguments: <the arguments you were given, or none>. Run it fully and reply with its final report only." — then show the user that report and stop. If you cannot see earlier user messages, or your only earlier message is that instruction to invoke dx-core:dx-plan-resolve (you are a fork or that subagent), continue below.

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 <!-- standalone-only --> 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:

1. Risks section — anything listed under ## Risks
2. Blocked steps — steps with **Status:** blocked
3. 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"

1. Search for existing repeatable fields that use show/hide → Grep for the show/hide pattern in config files
2. Find how they handle scoping → read the matching config and any companion JS
3. Identify the concrete pattern (scoped CSS classes, row-targeted selectors, etc.)
4. 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

1. /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.

2. /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.

3. /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)

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

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