plan ยท diff
git:20260909.e1fae0d to git:20260909.600c2eb
38 added, 56 removed. Audit A to A.
---
name: plan
description: 'Shape or refine the existing bead or caller intent in place. Triggers: "plan", "discover and plan", "shape this goal", "review write scope", "check scope boundaries", "scope this change".'
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 what is missing from the authorized intent. Prefer the caller's tracker, if any;
- otherwise use the caller's conversation or supplied text. A clear trivial change
- needs no planning worksheet or separate Plan dispatch. Planning produces no AgentOps packet.
+ 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.
## Workflow
- 1. Read the actual intent, relevant source owners and active constraints. Find
- the caller-visible outcome, allowed write scope and first useful check.
- Inspect only enough context to resolve a consequential uncertainty.
- 2. Where needed, clarify acceptance examples, important non-goals and scope in
- the existing source. Include generated companions as a class: hand-edited
- sources plus every output of the owning regeneration commands. Include tests
- and live consumers that must change with them. Scope is authority, not a
- prediction of an exact file count.
- 3. Choose the smallest acceptance-advancing action or discriminating check.
- Identify evidence the change could invalidate and include recapture where
- required. Use `ao provenance evidence-orphans` for affected bound evidence;
- avoid a mandatory ledger or taxonomy for changes that do not need one.
- 4. Revise the approach when evidence disproves an assumption under unchanged
- accepted outcome and scope. Record the disproved assumption, evidence and
- revised check briefly in the existing source or handoff. No new permission
- is needed for this approach revision. Changing acceptance or expanding scope
- needs caller authority; never quietly weaken the original check.
- 5. When another context needs the intent, pass enough exact source and references
- to act without the author's private reasoning. The runtime binds accepted
- intent for final validation; useful approach notes are separate from frozen
- acceptance so revising a hypothesis does not fabricate acceptance drift.
+ 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. Clarify missing acceptance examples and non-goals in that existing source.
+ 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. Keep approach notes separate from frozen acceptance. Do not transmit
+ the entire research history when a focused source reference will suffice.
- A plan is sufficient when the implementer can act and the validator can judge.
- Then stop planning and implement. Specialists and
- [ground-truth routing](references/ground-truth-routing.md) are optional tools for
- consequential integration or design uncertainty, not universal worksheets.
- [Memory recall](../memory/references/recall.md) is useful only when applicable
- prior experience may change this work's next action.
+ 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.
## Identity and scope
- Use the runtime's source reference and digest for exact accepted intent. For
- conversation-only intent, existing `ao provenance snapshot-intent --source -
- --evidence-root <explicit-root>` stores resolved bytes in a caller-selected
- protected external non-Git evidence directory. Missing routing does not authorize
- a workspace fallback or a second plan artifact. Preserve legacy proof.
-
- Scope patterns are normalized repository-relative paths, cover the behavior,
- and include generator-owned companions without granting unrelated directories.
- A live consumer outside accepted scope needs a concise exact-file amendment to
- the caller; continue independent authorized work while that decision is pending.
- [Boundaries](../rpi/references/boundaries.md) keep work/status in the caller's
- tracker and Git/delivery under repository policy.
-
- ## Prompt
-
- ```text
- Use Plan to resolve the uncertain parser interface for this accepted change.
- Keep acceptance and scope; use a real consumer check to test the assumption.
- Revise the approach if it fails, then implement. No new planning artifact.
- ```
-
- ## It's working if
+ 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-selected protected external
+ non-Git storage. Missing routing permits neither workspace fallback nor a
+ second planning artifact. Preserve legacy proof.
- A clear small change skips planning paperwork. A falsified assumption changes
- the approach and the next check; it does not trigger another approval round
- unless outcome or scope changes. Generated outputs remain in scope and the
- existing intent gives a fresh implementer enough information to act.
+ Use normalized repository-relative scope patterns. An uncovered live consumer
+ needs a concise exact-file amendment to the caller; continue independent
+ in-scope work meanwhile. Generated companions already in scope need no extra
+ permission. [Boundaries](../rpi/references/boundaries.md) keep work/status in
+ the caller's tracker and delivery under repository policy.