Next best action
Contract
| Field |
Bound contract |
| Trigger |
A project is between phases, the author asks what to do next, too many valid threads are open, or the work needs re-entry into frame, build, drive, memo, assumption testing, restart, or ship |
| Authority |
Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect |
None: returns one action recommendation |
| Done |
The recommendation cites the state it read; there is exactly one next action; the action has a clear done-when observable; a reader can tell why this action beats the other visible options |
Inputs
- Project state description from the author: where the project is, what is blocked, what the goal is. Required: absent required state blocks the skill; it does not proceed with caveats.
- Current supplied context: any plan files, task lists, or recent task outputs present in the conversation's current context. Optional.
- Explicit redacted evidence: any named artifact the author explicitly supplies as redacted evidence for this invocation. Optional.
- Named current task/plan artifacts: any plan, brief, or task file reachable as a named artifact in the current session. Optional.
Procedure
- Read the current supplied context: plan files, task lists, recent task outputs, and named current task/plan artifacts present in the conversation. Done when: all available context is read.
- Identify the highest-priority unblocked task, the most critical blocker, or the single action whose completion would most advance the stated goal. Done when: one candidate action is identified.
- Select exactly one action as the next best action. Done when: exactly one action is selected.
- Cite the specific evidence from step 1 that supports this selection. Done when: the evidence citation names the source artifact or context.
- State the done-when observable: a concrete, verifiable condition that marks the action complete. Done when: the done-when is observable and verifiable.
- Name one alternative option that was considered and state why the selected action beats it. Done when: one alternative is named with a stated reason the selection wins.
Failure and recovery
| Failure class |
Condition |
Result |
| insufficient-state |
No author-supplied state description and no current supplied context reachable as a named artifact |
Block: return "blocked: insufficient state, supply a project state description or make a plan/task artifact available in the current context" |
| missing-required-evidence |
Author-supplied state description is absent |
Block: do not proceed; return "blocked: required project state description missing" |
| ambiguous-priority |
Multiple actions tie for highest priority |
Pick one based on the author's stated goal; note the tie in the recommendation |
| no-clear-done-when |
Selected action has no observable completion condition |
Do not return it; state "no clear next action" and stop |
Partial-result rule: if optional evidence exists but is incomplete, return what is readable with a caveat that the recommendation is partial.
Non-mutation rule: authority is read-only; return no changes to any file, variable, or state.
Output
One prioritized action recommendation: next action, evidence citation, done-when observable, reason it beats one alternative, in that order, plain text, exactly one action.
1---2name: next-best-action3description: Use when a project is between phases, the author asks what to do next, too many threads are open, or work needs re-entry. Not for gating whether one named task may proceed.4---56# Next best action78## Contract910| Field | Bound contract |11|---|---|12| Trigger | A project is between phases, the author asks what to do next, too many valid threads are open, or the work needs re-entry into frame, build, drive, memo, assumption testing, restart, or ship |13| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. |14| Side effect | None: returns one action recommendation |15| Done | The recommendation cites the state it read; there is exactly one next action; the action has a clear done-when observable; a reader can tell why this action beats the other visible options |1617## Inputs1819- Project state description from the author: where the project is, what is blocked, what the goal is. **Required: absent required state blocks the skill; it does not proceed with caveats.**20- Current supplied context: any plan files, task lists, or recent task outputs present in the conversation's current context. Optional.21- Explicit redacted evidence: any named artifact the author explicitly supplies as redacted evidence for this invocation. Optional.22- Named current task/plan artifacts: any plan, brief, or task file reachable as a named artifact in the current session. Optional.2324## Procedure25261. Read the current supplied context: plan files, task lists, recent task outputs, and named current task/plan artifacts present in the conversation. Done when: all available context is read.272. Identify the highest-priority unblocked task, the most critical blocker, or the single action whose completion would most advance the stated goal. Done when: one candidate action is identified.283. Select exactly one action as the next best action. Done when: exactly one action is selected.294. Cite the specific evidence from step 1 that supports this selection. Done when: the evidence citation names the source artifact or context.305. State the done-when observable: a concrete, verifiable condition that marks the action complete. Done when: the done-when is observable and verifiable.316. Name one alternative option that was considered and state why the selected action beats it. Done when: one alternative is named with a stated reason the selection wins.3233## Failure and recovery3435| Failure class | Condition | Result |36|---|---|---|37| insufficient-state | No author-supplied state description and no current supplied context reachable as a named artifact | Block: return "blocked: insufficient state, supply a project state description or make a plan/task artifact available in the current context" |38| missing-required-evidence | Author-supplied state description is absent | Block: do not proceed; return "blocked: required project state description missing" |39| ambiguous-priority | Multiple actions tie for highest priority | Pick one based on the author's stated goal; note the tie in the recommendation |40| no-clear-done-when | Selected action has no observable completion condition | Do not return it; state "no clear next action" and stop |4142Partial-result rule: if optional evidence exists but is incomplete, return what is readable with a caveat that the recommendation is partial.43Non-mutation rule: authority is read-only; return no changes to any file, variable, or state.4445## Output4647One prioritized action recommendation: next action, evidence citation, done-when observable, reason it beats one alternative, in that order, plain text, exactly one action.
OutlineDriven