strikethroo 3.21.2 → 3.22.0

package/templates/harness/skills/st-refine-plan/SKILL.md

@@ -5,8 +5,6 @@ description: Use when the user asks to review, refine, improve, interrogate, pre
 
 # 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.
@@ -15,49 +13,46 @@ The user supplies the numeric plan ID conversationally, plus any optional refine
 
 ### 1. Locate the strikethroo root
 
-Run `scripts/find-strikethroo-root.cjs` from the user's working directory.
+Run `scripts/find-strikethroo-root.cjs` from the user's working directory. If
+it exits non-zero, stop and ask the user to run `npx strikethroo init`.
+
+Treat the path it prints as `<root>` for every subsequent step.
 
-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.
+Delegated execution workers skip this step and do not emit update notices.
 
-For every subsequent step, treat the path printed by this script as `<root>`.
+Run `scripts/check-for-updates.cjs "<root>"` as a separate command using this
+skill's script path. Keep the user's working directory. Read the one JSON line
+on stdout. When `notice` is present, retain its exact text for the final
+user-facing response. Never pause for permission and never run an update.
 
 ### 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.
+Run `scripts/validate-plan-blueprint.cjs <plan-id> planFile` for the plan
+file's absolute path. Another field name prints that field instead.
 
 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.
+Read `<root>/config/STRIKETHROO.md` for this project's directory conventions.
+Read `<root>/config/hooks/PRE_PLAN.md` and execute its instructions before
+proceeding. Read `<root>/config/templates/PLAN_TEMPLATE.md`; the refined plan
+must still conform to it. Read `<root>/config/shared/clarification-gate.md`
+and apply it in the Clarification Loop.
 
 ### 4. Baseline Review
 
-Read the entire plan end-to-end. Without modifying the file:
+Read the entire plan end-to-end without modifying it. Record every
+contradiction and every gap you find under these lenses:
 
-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.
+- **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}`.
+Document each one as `{section, issue, severity, proposed fix}`.
 
 ### 5. Clarification Loop
 
@@ -73,106 +68,65 @@ 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.
+Either branch starts from the gaps documented in the Baseline Review. Think
+harder before raising one: only put forward an uncertainty you can cite.
+Append every resolution to the plan document's "Plan Clarifications" table in
+its existing question/answer format, marking each entry's source.
 
 #### 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.
-4. Prefill each question with the most plausible answer so the user can
-   confirm or deny quickly.
-5. Always include an "Other / open-ended" option to capture nuances you did
-   not anticipate.
-6. **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
+1. Ask one question at a time per that cadence; never dump them as a batch.
+2. Prefill each question with the most plausible answer, and always offer an
+   "Other / open-ended" option for the nuances you did not anticipate.
+3. **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 step 6
    until you have received explicit answers and confirmed the resolved scope.
-7. 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.
-8. Re-evaluate whether new gaps emerged from the answers. If so, repeat
-   this loop.
+4. Record a question the user cannot or will not answer as unresolved, with
+   mitigation notes so downstream assistants know the risk, then proceed with
+   the available context.
+5. Re-evaluate whether the answers opened new gaps. 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.
-3. 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).
-4. For truly unresolvable questions, record them as unresolved with
-   mitigation notes so downstream assistants know the risk.
-5. If no gaps remain (or all have been resolved or documented), proceed to
-   Stage 6.
+1. Resolve each gap from the codebase, its configuration files, its
+   documentation, and the project's established patterns. Fall back to a
+   reasonable assumption only where those do not answer it.
+2. Mark each resolution's source as "auto-resolved" (confirmed in the
+   codebase) or "assumption" (best-effort guess, with its rationale).
+3. Record a gap you can resolve neither way as unresolved, with mitigation
+   notes so downstream assistants know the risk.
 
 ### 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.
+Refine the plan in place, at the path step 2 resolved.
 
-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.
-2. **Structure Compliance**: Ensure the plan still follows
-   `<root>/config/templates/PLAN_TEMPLATE.md`. Add missing sections if
-   necessary.
+1. **Maintain Identity**: Keep the existing `id` and directory. Never allocate
+   a new plan ID and never move the plan.
+2. **Structure Compliance**: Keep the plan conformant to
+   `<root>/config/templates/PLAN_TEMPLATE.md`, adding any missing section.
 3. **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).
-4. **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.
-5. **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`).
+   - Refresh the executive summary against the clarifications.
+   - Update the architectural sections, diagrams, and risk mitigations the
+     gaps named.
+   - Trim scope creep that is not explicitly required.
+   - Point each affected section back at the Q&A table.
+4. **Net-New Sections**: Add a subsection the plan now needs (Decision Log,
+   Data Contracts) under `Notes`, clearly labeled.
+5. **Change Log**: Append to `Notes` a bullet stating what this session
+   changed, such as
+   `- 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]
-```
+Execute `<root>/config/hooks/POST_PLAN.md`.
 
-The summary is consumed by downstream automation; keep the format exact.
+When the retained update `notice` is present, append that exact sentence after
+the structured summary block, or after your final response when this skill emits
+no summary block. Nothing may follow the notice.
 
 ## 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.