st-refine-plan

Drive the end-to-end refinement of an existing Strikethroo plan.

Inputs

The user supplies the numeric plan ID conversationally, plus any optional refinement notes.

Operating Procedure

1. Locate the strikethroo root

Run scripts/find-strikethroo-root.cjs from the user's working directory.

If the script exits non-zero, the working directory is not inside an initialized strikethroo workspace. Stop and ask the user to run the project initializer (e.g. npx strikethroo init) before continuing. Do not attempt to refine a plan outside of a valid root.

For every subsequent step, treat the path printed by this script as <root>.

2. Resolve the plan

Run scripts/validate-plan-blueprint.cjs <plan-id> planFile to obtain the absolute path of the plan file. Passing a different field name prints that field alone.

If the script exits non-zero, stop and ask the user to confirm the plan ID. Do not guess a different ID.

3. Load project context

Read these files, in order:

• <root>/config/STRIKETHROO.md — directory conventions and project context.
• <root>/config/hooks/PRE_PLAN.md — execute the instructions it contains

before proceeding.

• <root>/config/templates/PLAN_TEMPLATE.md — the structural baseline the

refined plan must continue to conform to.

• <root>/config/shared/clarification-gate.md — apply in the Clarification Loop.

4. Baseline Review

Read the entire plan end-to-end. Without modifying the file:

1. Capture key metadata (plan title, summary, creation date, related initiatives).
2. Surface the strongest sections, contradictions, and potential risks.
3. Identify gaps using these lenses:

- Context gaps: missing background, assumptions, competing priorities. - Technical gaps: underspecified architecture, unclear interfaces, missing diagrams. - Risk gaps: untracked risks, missing mitigations, hand-wavy success metrics. - Scope issues: gold-plating, ambiguous boundaries, requirements that contradict YAGNI.

Document each gap with {section, issue, severity, proposed fix}.

5. Clarification Loop

Default to Interactive Clarification. Switch to Autonomous Clarification only when one of these holds without interpretation:

• The user's request names the mode by intent, with a keyword such as "auto",

"autonomous", "non-interactive", "without asking me", or "don't ask".

• An upstream orchestrator (for example the st-full-workflow skill) declared

autonomous operation for this invocation in the prompt passed to this skill.

Otherwise use Interactive Clarification, even when the user's presence is uncertain. Do not infer autonomous mode from indirect signals such as terse prompts, scripted-looking input, or absence of recent user messages.

After the clarification loop completes, append all new findings to the "Plan Clarifications" section in the plan document using the existing format (table with question/answer pairs). Mark the source of each entry appropriately.

Interactive Clarification

Think harder before interrupting the user — only trigger this loop when you can cite concrete uncertainties.

Follow the clarification cadence in <root>/config/shared/clarification-gate.md.

1. Review the gaps documented in the Baseline Review.
2. If no gaps remain, stop here and proceed to Stage 6.
3. Group the open questions by theme, but ask them one at a time per the

cadence above rather than dumping them as a single batch.

1. Prefill each question with the most plausible answer so the user can

confirm or deny quickly.

1. Always include an "Other / open-ended" option to capture nuances you did

not anticipate.

1. STOP AND ASK: Put each question to the user and halt execution to await

their input. Do not simulate the user's response. Do not proceed to Stage 6 until you have received explicit answers and confirmed the resolved scope.

1. After receiving answers, record them in the Plan Clarifications table.

If the user cannot answer a question, record it as unresolved with mitigation notes so downstream assistants know the risk.

1. Re-evaluate whether new gaps emerged from the answers. If so, repeat

this loop.

Autonomous Clarification

Think harder before flagging gaps — only document concrete uncertainties you can cite.

1. Review the gaps documented in the Baseline Review.
2. For each gap, attempt to resolve it by:

- Inspecting the codebase, configuration files, and documentation. - Analyzing existing patterns and conventions in the project. - Reviewing assistant documents and README files. - Making reasonable assumptions based on common practices and project context.

1. Record all resolutions in the Plan Clarifications table. Mark each

entry's source as either "auto-resolved" (confirmed via codebase) or "assumption" (best-effort guess with rationale).

1. For truly unresolvable questions, record them as unresolved with

mitigation notes so downstream assistants know the risk.

1. If no gaps remain (or all have been resolved or documented), proceed to

Stage 6.

6. Refinement Implementation

Once you have sufficient context (or have documented all missing context), refine the plan directly in-place. The plan file path is the one returned by step 2.

1. Maintain Identity: Keep the existing id and directory. Do not create

a new plan ID. Do not move the plan to a new location.

1. Structure Compliance: Ensure the plan still follows

<root>/config/templates/PLAN_TEMPLATE.md. Add missing sections if necessary.

1. Content Updates:

- Refresh the executive summary to reflect clarifications and new insights. - Update architectural sections, diagrams, and risk mitigations to resolve the identified gaps. - Trim any scope creep that is not explicitly required. - Clearly reference clarifications in the relevant plan sections (e.g., italicized notes that point back to the Q&A table).

1. Net-New Sections: If the plan needs a new subsection (e.g., Decision

Log, Data Contracts), add it under Notes with a clearly labeled section so it remains discoverable.

1. Change Log: Append a bullet list in the Notes section that briefly

states what changed in this refinement session (e.g., - 2025-03-16: Clarified auth flow tokens and updated architecture diagram).

7. Run the post-plan hook

Execute <root>/config/hooks/POST_PLAN.md after the plan file is updated.

8. Emit the structured summary

Conclude with exactly this block as the final output:

---

Plan Refinement Summary:
- Plan ID: [numeric-id]
- Plan File: [absolute-path-to-plan-file]

The summary is consumed by downstream automation; keep the format exact.

Failure Modes

• User refuses to answer a clarifying question that blocks refinement.

Record the unresolved question in the Plan Clarifications table with mitigation notes, proceed with available context, and flag the remaining risk in the Refinement Report.

• A helper script fails unexpectedly. Surface stderr to the user and

stop — do not fall back to manual path discovery.

• Plan file is missing after resolution. This indicates a consistency

issue in the strikethroo workspace. Stop and report the error without attempting to recreate the plan.