unkos-dev Planning a change
The plan's reader is an agent with no prior context. Planning is read-only apart from the plan files the user authorises. Do not implement, create a branch, commit, publish, or mutate a tracker. Approval of a plan grants no implementation authority.
Resolve authority and intent
Read the applicable repository instructions and planning convention first. Treat issues, discussions, existing code, and prior plans as evidence rather than authority. In a Specful repository, Requirements and Designs constrain the delivered state, accepted ADRs constrain durable choices, and a plan remains temporary transition coordination.
Apply the development workflow: start at
docs/specs/index.md, follow scope indexes and relevant Requirements, Designs and ADRs, then inspect the targeted code
and existing tests. Use broader search when coverage or directions are missing or inaccurate. Identify the affected
acceptance criteria and the evidence needed to check them. If a worthwhile artifact is missing, propose its subject,
type and durable benefit and obtain the user's decision and input before authoring; planning remains read-only apart
from authorised plan files. This navigation also applies to bounded work that needs no saved plan.
Establish the problem, intended outcome, fixed constraints, and the observable result. Preserve authoritative and explicitly approved decisions. Surface contrary evidence instead of silently reopening or overriding them.
Decide whether design is settled
Read planning craft and state the invariant before judging the design. Proceed directly when the governing artifacts and approved discussion settle the material design. Otherwise inspect the repository, gather only evidence that can change the approach, present credible options with a recommendation, and wait for the user's decision before writing tasks.
Gather evidence the executor would otherwise rediscover: precise path:line references, the primitives and extension
points that already exist, the closest useful precedent, the repository's verified validation commands, and the
conventions the change must preserve. Inspect the decisive files directly.
Diagnose asserted broken behaviour before planning a fix. Use external research, a throwaway spike, or delegation only when its result can materially change the plan. The workflow must remain executable by one capable agent.
Select the planning shape
- Do not create a saved plan for clear, bounded work unless the user requests one.
- Use one change plan for one coherent deliverable.
- Use an arc plan when several changes are independently deliverable or have meaningful dependency or decision gates. One step is one pull request; a step's own change plan exists only when the step needs a standalone execution packet, and it cites the arc's step and task numbers rather than restating them.
- For implementation planning, write the arc and the first executable step's change plan when that step needs one. Write later steps' change plans from delivered evidence, never from assumptions.
Follow the repository's existing plan location, plan template, tracking, and retention policy. Propose docs/plans/
only when no location is established. If tracking policy is absent, ask once whether plans should be tracked or ignored
before writing. When the repository defines no filename convention, use YYYY-MM-DD-<descriptive-slug>.md. A template
is a file the repository designates as one; prior plans are evidence of convention, not templates. An explicit user
choice wins.
By default, confirm a plan's exclusion from Git and documentation publishing inputs before writing; a location under
docs/ does not imply publication intent. Obtain approval for any needed ignore or publishing configuration changes; do
not make them automatically. Keep plans outside the permanent corpus; they are not inputs to Specful indexing or
validation.
Write the plan
For a change plan, read the change-plan template. For an arc, read
the arc-plan template. Use the repository's own plan template when it exists. Keep every
section; a section that does not apply says so with the reason. Remove an optional frontmatter field that does not
apply. type, status, and created are required. issue, relates-to, and part-of are optional where present.
Every statement in a plan is exact; the executor treats deviation as a stop. State an open choice in its task with the reason. Write tasks verb-first. Every task verifies with a command and its expected output, and the command fails when that task's behaviour is absent. When a task creates or replaces a short file whose content is the specification, quote the exact content in the task. Quote an indented replacement line in a fenced block, never a code span. A step's Context describes the repository state when the step starts, not the history that produced it.
A maintainer-owned act that must happen after the pull request is green and before merge, such as a required-check change, is recorded under Merge conditions. It is never a task or a prerequisite, and the executor reports it unrun.
Issue and tracker inputs may supply context. Follow discussion and linked material only while they can change scope, authority, or decisions. Never publish or update external state without separate authority.
Review and hand off
Check the plan against each item, then fix what fails:
- every cited path, line range, command, and dependency exists; a dependency is declared in the importing package's manifest, not its lockfile;
- every step or task can be executed from its own section plus Binding inputs, Design decisions, and Verification;
- no two steps share a verification command unless they change the same behaviour;
- every exit criterion and expected output is checkable without judgement;
- every step with an irreversible effect has a rollback;
- every declared dependency edge matches an artifact one step produces and another consumes;
- every open choice names what is open and why;
- every deliverable in the objective maps to a task and a verification row;
- every Verify command has been run once against the current tree and fails as absence predicts; a command the repository's hooks refuse is rewritten, and a command that would mutate the tree is run in its dry or frozen form;
- every check that asserts absence names what its pattern matches on the current tree, and each match is something a task removes;
- every file a task moves has every path-keyed ignore or allowlist entry for it updated in the same task, because what commit hooks do to a file at its path is task state;
- a whole-tree search for every identifier and path the change renames has been run, and every hit is a Do step;
- every count and quantity stated in prose matches its source;
- no placeholder, narrative paragraph, or generic example remains.
Run the repository's applicable document checks, naming the plan file's path when the plan directory is ignored by version control, or report that none are defined after checking its instructions and command surfaces. Record defects in the convention or its skills in the adopter's own record, never in the plan.
Report the written paths, selected shape, approved decisions, open decisions, first executable step, and verified commands. Stop there. The user separately decides whether to review or implement the plan.