/plan

name: plan
description: 'Define intended behavior, review write scope and assess reversible decisions. Use when: acceptance or approach is unclear before coding; stop once actionable.'
practices:
- bdd-gherkin
- design-by-contract
- ddd-bounded-context
hexagonal_role: domain
consumes: []
produces: []
output_contract: 'in-place caller intent update or concise proposed amendment; never an AgentOps planning artifact'
context_rel: []
skill_api_version: 1
user-invocable: true
metadata:
  graph_root: true
  tier: execution
  dependencies: []
  capabilities: [shape_intent, define_acceptance, bound_write_scope]
  effects: [update_intent_source]
  canonical_status: canonical
  disposition: keep

Plan

Shape only missing intent. Prefer the caller's tracker, if any; otherwise use the conversation or supplied text. Planning produces no AgentOps packet. A clear change can proceed directly. Use established domain names throughout intent, examples, code and validation; [Domain](../domain/SKILL.md) helps when meanings or boundaries are genuinely unclear.

Workflow

1. Read accepted intent and relevant source owners and active constraints. Resolve only consequential uncertainty; do not reopen settled decisions without new evidence. Identify the caller-visible outcome, scope and first useful check. 2. Describe the intended observable behavior before implementation. Reuse acceptance already supplied in the conversation or bead; clarify only what prevents action or judgment. Name the actor or caller, the event and the observable result. One example often suffices; use Given/When/Then for branching behavior and consequential boundaries. Include non-goals only where they prevent a plausible scope mistake in that existing source. If the caller requests both code and a retrospective, distinguish code acceptance, delivery facts and the later analysis in that same intent. Code judgment consumes acceptance and checks; the retrospective consumes the known outcome and judgment. Keep both requested deliverables required for the overall goal without making either depend on its own conclusion. Scope includes the hand-edited owners, affected tests/live consumers and generator-owned companions as a class; it is authority, not a predicted file count. A consequential assumption deserves an early discriminating check, not a general checklist or exhaustive survey. 3. Choose the smallest action that advances acceptance or falsifies the risky assumption. Include recapture of affected bound evidence where necessary; use `ao provenance evidence-orphans` when applicable, not a mandatory ledger. 4. When evidence disproves an approach, briefly retain the failed assumption, evidence and revised check in the existing intent or handoff. Approach changes within accepted outcome and scope need no new permission; acceptance or scope expansion requires caller authority. Never relabel a failed acceptance condition as a caveat to obtain green. 5. Give another context exact intent references and the evidence it needs to act, its write scope and who owns integration and final review. Keep approach notes separate from frozen acceptance. Pass the next decision and relevant source references, not the entire research history. A new goal does not clear an existing conversation, and a fresh context can still have large startup instructions, tool catalogs and retrieved inputs.

Stop planning once the implementer can act and the validator can judge. More research, decomposition or review must resolve a named remaining uncertainty. Specialists and [ground-truth routing](references/ground-truth-routing.md) are optional. [Memory recall](../memory/references/recall.md) is useful only when prior evidence could change the next action.

Behavior and naming

An example can be plain text; BDD does not require a `.feature` file or an interview. For example, in a repository that calls queued work a **Job**:

> Given a Job has already completed, when the worker receives it again, > then its completed result is returned and its side effect is not repeated.

Use the actual domain term instead of inventing a parallel label such as "task item." Identify what the caller can observe and the smallest check that distinguishes the desired behavior from the current failure. Keep the accepted example available to Implement and Validate. Tests added after coding may supplement it; they cannot redefine what was promised.

For uncertain designs, probe the assumption that could change the approach. For product planning, distinguish demonstrated behavior from aspiration and refine the existing product owner only within the request. A product document is not required for an ordinary feature.

Decision cost and stopping

Use real undo cost, affected users and existing authority when choosing who must decide. Resolve reversible implementation details within accepted scope. A material irreversible choice outside that authority needs the caller; prior authorization remains valid. Reviewer agreement is evidence, not permission to replace the caller's intent. Explain a consequential disagreement and its support rather than silently changing acceptance.

A proposed process artifact earns its cost only with a concrete consumer, subject or release decision, observed defect and retirement condition. If the next action adds only ceremony or repeats settled evidence, omit it. Stop when the implementer can act and the validator can judge, reserving capacity for implementation, integration and repair.

This guidance adapts the intent-first approach in [Matt Pocock's engineering skills](https://github.com/mattpocock/skills) using AgentOps' existing intent and evidence contracts.

Identity and scope

Use runtime-derived source identity and digest. If conversation intent needs an exact snapshot, existing `ao provenance snapshot-intent --source - --evidence-root <explicit-root>` uses caller-s