workflow-next-step

Workflow Next Step

Use this skill as the final handoff phase after a core compound-engineering workflow completes. Inspect repo artifacts, mark completed phases for the current feature or maintenance lane, and tell the user exactly what to run in the next session.

This is an advisor, not another workflow phase. It must make one narrow decision: given the artifacts that already exist, what is the next safest command or skill to run, with which inputs?

Core Graph

Full feature delivery path:

constitution -> brainstorm -> grill-with-docs -> plan -> architecture -> deepen-plan -> to-issues -> work -> review -> triage -> compound

Lite feature path:

brainstorm/plan --lite -> work -> review -> triage if review creates todos -> compound if reusable knowledge exists

Side lanes:

• debug diagnoses failures, then either fixes locally or hands off to brainstorm, plan, architecture, deepen-plan, or to-issues.
• compound-refresh maintains existing docs/solutions/ knowledge and is not part of one feature's delivery chain.

Inputs

Infer the current workflow from the just-finished command when possible. Otherwise infer from the newest relevant artifact and user context.

Prefer explicit paths over discovery:

1. command argument paths
2. paths printed by the completed workflow
3. frontmatter refs in known artifacts
4. newest matching artifacts by date and topic

When discovering or matching the plan artifact, treat either docs/plans/YYYY-MM-DD-*-plan.md or docs/plans/YYYY-MM-DD-*-plan.html as the plan (dual-read by extension). Brainstorm and architecture artifacts are dual-read the same way -- .md legacy or .html since T03 (brainstorm) and T04 (architecture) respectively; see the brainstorm and architecture rows in Artifact Checks below. Tickets, execution sessions, and solutions stay .md-only.

Never mark a step complete only because an unrelated file exists. Match by explicit ref, topic slug, date proximity, source path, or parent/child frontmatter.

Advisor Procedure

Run the advisor in this order. Do not jump directly from the just-finished command to a recommendation.

1. Identify the active lane: choose full feature, lite feature, debug side lane, or maintenance lane.
2. Bind the current chain: collect only artifacts that belong to the same feature, bug, plan, ticket set, execution session, or maintenance target.
3. Audit completion evidence: evaluate every relevant checklist row against the artifact checks below.
4. Summarize completed stages: extract one precise handoff summary for each completed stage in the current chain.
5. Apply decision gates in order: resolve blockers, optional advisor-owned actions, then the graph transition.
6. Emit one next-session directive: output the exact command or skill invocation and the inputs needed to run it.

Current Chain Selection

Treat artifacts as belonging to the same chain only when at least one of these links is present:

• a direct path from the completed workflow output
• a parent/child ref such as brainstorm_ref, plan_ref, architecture_ref, tickets_ref, or execution-session source path
• the same date/topic slug plus consistent title, problem statement, or feature home
• a ticket index that points back to the plan being evaluated
• todos created by the review summary for the same work/review scope
• a debug result that names the affected feature, command, failing test, or source artifact

If chain identity is ambiguous, do not infer completion from nearby files. Mark the uncertain step as unchecked and set the next recommendation to the narrowest clarifying workflow or artifact review that can resolve the ambiguity.

Artifact Checks

Use these checks to decide whether each step is complete for the current feature.

Step	Completion evidence
constitution	docs/constitution.md exists with active/versioned constitution content. Optional for a feature unless the repo already has one.
brainstorm	Matching docs/brainstorms/YYYY-MM-DD-*-brainstorm.md (legacy) or docs/brainstorms/YYYY-MM-DD-*-brainstorm.html (since T03) exists with status: complete, all handoff.* fields true, and no unresolved open questions. For .html, read these same fixed-core facts from the brainstorm's #artifact-data JSON island via commands/workflows/references/html-artifacts/island-extraction-helper.md instead of frontmatter/sections — never scrape the rendered HTML, and never fall back to a .md mirror.
grill-with-docs	CONTEXT.md exists or was updated with canonical glossary terms, and the active brainstorm or plan has inline additions to decision-bearing sections such as ## Chosen Approach, ## Key Decisions, ## Architectural Context, ## Resolved Questions, ## Implementation, or execution packets.
plan	Matching docs/plans/YYYY-MM-DD-*-plan.md (legacy) or docs/plans/YYYY-MM-DD-*-plan.html (pilot HTML-artifact output) exists with status: active or later, handoff.* true, tdd, execution_shape, runtime/e2e sections, and execution packets. For .html, read these same fixed-core facts from the plan's #artifact-data JSON island via commands/workflows/references/html-artifacts/island-extraction-helper.md instead of frontmatter/sections — never scrape the rendered HTML, and never fall back to a .md mirror.
architecture	Matching docs/architecture/YYYY-MM-DD-*-architecture.md (legacy) or docs/architecture/YYYY-MM-DD-*-architecture.html (since T04) exists and the parent plan records it with architecture_ref or a labeled related-artifact link. For .html, read these same fixed-core facts from the architecture artifact's #artifact-data JSON island via commands/workflows/references/html-artifacts/island-extraction-helper.md instead of frontmatter/sections — never scrape the rendered HTML, and never fall back to a .md mirror.
deepen-plan	The selected plan was updated by deepening, or a *-plan-deepened.md/*-plan-deepened.html file exists (dual-read by extension, same as the plan row above); WHY handoff remains intact; architecture artifact or explicit handoff was consumed.
to-issues	docs/tickets/YYYY-MM-DD-<topic>/index.md exists with ticket files, dependency graph, execution batches, last_completed_batch, and the parent plan records tickets_ref or a labeled related-artifact link.
work	docs/execution-sessions/work-*/STATE.md for the current plan/ticket source has status: completed, unit files exist, relevant plan/ticket statuses were updated, and validation/evidence is recorded.
review	A review summary was produced, TDD/e2e evidence was checked when relevant, and review findings were either absent or written to todos/.
triage	Targeted todo files are complete or explicitly blocked, with selected actions, research notes, and validation/work logs recorded.
compound	A relevant docs/solutions/<category>/<filename>.md exists for a non-trivial solved problem, or the workflow explicitly determined no reusable knowledge needed capture.

Stage Summaries

The advisor must summarize previous steps so the next session can restart without re-reading the whole chain. Summaries must be factual, path-grounded, and short.

For each completed stage in the active chain, include exactly one bullet in Completed Stage Summaries:

• constitution: governing constraint, version/date, or why constitution was not needed for this feature
• brainstorm: user story, chosen approach, key constraints, and unresolved-risk status
• grill-with-docs: canonical terms/boundaries added to CONTEXT.md and the brainstorm/plan section that was enriched
• plan: execution shape, TDD/evidence contract, packet count, runtime/e2e expectations, and known scope fences
• architecture: feature home, shared/global boundary decisions, interfaces/contracts, and deepening candidates
• deepen-plan: major hardening decisions, research/review conclusions, and whether ticketization is now warranted
• to-issues: ticket index path, execution batches, dependency graph status, and next batch cursor
• work: execution-session state path, completed units/batches, validation evidence, and source status updates
• review: review result, findings count, todo paths or "no todos", and any evidence gaps
• triage: todo scope resolved, code/doc changes made, validation evidence, and remaining blocked items
• compound: solution doc path or explicit no-capture rationale
• debug: reproduced trigger, root cause/failure mechanism, fix status, and named Fix or next step
• compound-refresh: refreshed solution docs, stale docs left blocked, and validation performed

Do not summarize stages that are merely adjacent or discovered by date. If a stage is incomplete, summarize the missing requirement in Workflow Progress instead of pretending there is a completed-stage summary.

Routing Rules

Apply these rules only after the advisor procedure and artifact checks are complete.

Decision Gate Order

1. Validity gate: If the just-finished artifact fails its required checks, recommend the same workflow again or document-review <artifact-path> when review can repair ambiguity without rerunning the workflow.
2. Blocked-input gate: If the next graph step lacks a required input path, recommend the narrowest command or skill that can produce or identify that input. Do not invent a path.
3. Graph gate: If the artifact is valid and inputs are known, recommend the next graph command from the stage rules below.
4. Stop gate: If the chain is complete or the lane is maintenance-only, recommend complete with no command required.

Stage Rules

1. After constitution, recommend /workflows:brainstorm <feature-or-goal> when no feature artifact exists. Recommend /workflows:plan <existing feature description or brainstorm path> only when the user already supplied a clear feature description or a matching brainstorm exists.
2. After brainstorm, recommend grill-with-docs before planning unless the request is explicitly lite/trivial and no domain terms or open boundary questions exist.
3. After grill-with-docs, recommend /workflows:plan <enriched-brainstorm-path>.
4. After plan, recommend /workflows:architecture <plan-path>. Allow direct /workflows:work <plan-path> only for lite/small plans with an explicit architecture handoff.
5. After architecture, recommend /deepen-plan <plan-path>.
6. After deepen-plan, recommend /workflows:to-issues <plan-path> when the plan has a real architecture_ref and more than one execution packet, meaningful dependencies, or feature-home boundaries to preserve. Recommend /workflows:work <plan-path> only for compact/lite plans.
7. After to-issues, recommend /workflows:work <ticket-index-path>.
8. After work, recommend /workflows:review <ticket-index-or-plan-path> <execution-session-state> when ticketized execution was used; otherwise pass the plan path and execution session.
9. After review, recommend a full /workflows:triage command when current-review pending todos exist. Prefer the todo paths passed by the review workflow over broad discovery. If their numeric filename prefixes form a clear first-last span, use /workflows:triage todos <first>-<last> (for example, /workflows:triage todos 13-23). If they are non-contiguous or cannot be safely ranged, pass the narrowest exact scope or explicit todo paths instead of a bare command. If no todos exist, recommend /workflows:compound only when the solution was non-trivial or introduced reusable knowledge.
10. After triage, recommend another scoped /workflows:review <changed-scope> when triage executed code changes. If completed work is not committed and the user asked for shipping discipline, recommend git commit/git push as the next-session directive before review. Otherwise recommend /workflows:compound when reusable knowledge exists.
11. After compound, report the chain complete unless the user wants to add the learning to a skill or refresh existing docs.
12. After debug, recommend the command named in the debug result's Fix or next step. If the result is rethink design, prefer /workflows:brainstorm or /workflows:architecture according to the stated issue.
13. After compound-refresh, report maintenance complete and recommend the next feature workflow only when the user has an active feature artifact.

When several rules appear plausible, prefer the earliest incomplete graph stage in the active chain over a later convenience action. Never skip review after work, never skip triage when review-created todos are pending, and never skip compound when a reusable solution was produced.

Advisor-Owned Options

The core workflow commands do not present handoff menus. Preserve their former choices here as conditional recommendations, but output one recommended path, not a menu.

• Review/refine: Recommend document-review only when the just-written artifact is internally contradictory, missing required handoff fields, or likely to become a durable reference. Otherwise recommend the next graph step.
• Ask more questions / deepen further / other rework: Recommend returning to the same command only when required artifact checks fail or unresolved questions block routing.
• Issue creation: After plan, mention tracker issue creation only as an input/supporting action when explicitly requested by the user; do not let it replace /workflows:architecture.
• Open/view diff/revert: After plan or deepen-plan, include these only as optional human inspection notes under "Inputs to pass" or "Why this is next"; do not make them the recommended next command unless the artifact is invalid or the user explicitly asked.
• Commit/push after triage: Recommend commit/push only when triage executed changes that are complete and validated but not committed; otherwise route to review or compound.
• Done/stop: When no next workflow is needed, set the recommended next step to complete and state that no command is required.

Required Output

End with exactly these sections.

## Workflow Progress

- [ ] constitution — <artifact or reason not applicable>
- [ ] brainstorm — <artifact or missing requirement>
- [ ] grill-with-docs — <CONTEXT.md / feature-doc evidence or missing requirement>
- [ ] plan — <artifact or missing requirement>
- [ ] architecture — <artifact or missing requirement>
- [ ] deepen-plan — <artifact or missing requirement>
- [ ] to-issues — <artifact or missing requirement>
- [ ] work — <artifact or missing requirement>
- [ ] review — <artifact or missing requirement>
- [ ] triage — <artifact or missing requirement>
- [ ] compound — <artifact or missing requirement>

## Completed Stage Summaries

- `<stage>` — <one factual summary tied to an artifact path>

## Next Session

Recommended next step: `<command or skill name>`

Run it with:
```text
<exact command and arguments>
```

Inputs to pass:
- `<path or context>`

Why this is next:
- <one to three bullets tied to the artifact checks>

Stop condition for that next step:
- <artifact or state the next session should produce>

For a side lane, keep the same section names but clearly label the checklist as the nearest feature chain or "maintenance lane" when no feature chain is active.

Constraints

• Do not mutate artifacts while advising next steps.
• Do not invent missing paths.
• Do not summarize every file inspected; cite only the artifacts that explain the recommendation.
• Keep the output concise enough to paste into a new session.
• Prefer a single next command over a menu.