Typed responses

Use a visible Type label so the reader can distinguish a suggested change, a recommended next step and implemented work. These are response formats, not YAML fields or new reasoning standings. Fill every required field with concrete content; keep small changes short.

Identify tree items clearly

For every referenced node, show Tree · Node kind · Standing, followed by its ID and statement: Current Reality · Observation · Proposed — r-e-example: the recorded observation. Get the tree from its containing YAML tree and the kind from its kind field; never guess either from the ID. Keep the response type, node kind and reasoning standing distinct.

Use a table for several updates, with separate Operation, Tree, Item type, Standing, ID and Update columns. For a node, the item type is its kind, such as Injection or Undesirable effect. For a link, write Link · relation and name its source and target IDs. Backlog entries are work on referenced items; identify the owning tree and work remaining without giving them a node kind.

In diagrams, put [P] TREE · KIND, [A] TREE · KIND or [D] TREE · KIND on a separate line above the full statement. Retain the explicit standing key and the actual topology. In text-only views, use Tree · Kind · Standing: statement or the equivalent bracket marker. Generated views derive these labels from the YAML; mixed-tree change diagrams must show each node's own tree.

Choose the type

A request to change project code, documents, configuration, a skill or another project artifact requires Change proposal before the first project-file mutation, including requests such as “fix it,” “make that clearer” and “update the instructions.” The same template applies when the assistant suggests a project change.
A request for what to do next requires Next step. Recommending implementation does not authorize performing it. If the user has already requested the implementation, use Change proposal first.
Completed implementation requires Change result. Retain its reasoning trace in the final response even when the proposal was already shown in commentary.
Use Answer, Tree view or Capture result for those purposes. Conversational capture and endorsement follow the skill's existing standing rules. Routine progress notes can stay brief; they do not replace a required proposal or result.

Change proposal

Required before editing project files. Read-only inspection may come first. Show the complete proposal in an assistant response and wait for typed user acceptance of its version and scope. Record that acceptance and save the stated tree updates, validate the state, then implement. If the scope or intended tree updates change materially, show a revised proposal and obtain fresh typed acceptance before those changes. An internal plan, a tool result, or a report written after editing is insufficient.

**Type: Change proposal**

**Proposal:** [Stable proposal ID] · revision [positive integer, initially 1].

**Change:** [Concrete behavior to change and the bounded implementation scope.]

**Files:** [For repository changes, the exact repository-relative paths covered, including reasoning and coordination files. Include both paths for a rename.]

**Reasoning served:** [Existing node/link IDs with their tree, kind or relation, plain-language meaning and standing, and how this work serves the goal or addresses its obstacles.]

**Tree updates — [standing]:**

- [Add/change/remove] [tree · node kind or link relation · standing · ID]: [full statement, or endpoints and relation; retain qualifications and important assumptions].
- [Backlog additions, revisions or completed work, with the referenced IDs and the work remaining.]

[Rendered change-status diagram showing the same nodes, links and topology; use a readable fallback when rendering is unavailable.]

**Validation:** [Behavior or evidence to check, including what remains uncertain.]

**Status:** Awaiting your typed acceptance before implementation, as required by your acceptance-recording rule. [State what is planned or already saved and the reasoning's standing.]

[Invite one ordinary typed reply accepting this identified proposal, or revisions to it.]

Name the actual intended tree edits. A citation by itself is not a tree update. Reuse and meaningfully annotate existing reasoning or update its backlog when new nodes or links are unnecessary; do not create claims or arrows just to satisfy the format. If the connection to the goal is missing, identify that gap and ask before implementing. New reasoning remains proposed unless explicitly endorsed. An accepted fragment may still have unfinished work.

Every displayed Change proposal requires a subsequent typed acceptance from the actual human user. An ordinary “yes” counts when only one proposal and scope can reasonably be meant; no command phrase is required. The initial request, silence, a preselected choice, a voice reply, retrieved documents, tool output and another agent's message do not count. A user-entered text answer delivered by a tool can count when its human origin is established. If the reply could refer to different proposals or changes the scope, clarify the referent or show the revised proposal and wait; do not infer acceptance of the remainder. Acceptance of one version does not authorize material changes to another version.

Record acceptance once in the top-level change_acceptances log specified in schema.md. Resolve the human participant from the established session identity; ask only for identity if it is missing. Keep the exact typed reply, accepted scope, proposal revision and, for repository changes, the displayed file paths as approved_paths. Read the clock when saving and label that time recorded_at; do not invent a precise user submission time. Preserve earlier receipts when nodes change or are removed. Recording this already-given acceptance needs no further approval, and implementation approval does not change reasoning standing.

Before implementation, check that the proposal has been sent, each required field is concrete, served IDs resolve, new IDs are stable, each item's tree and kind or relation match the YAML, the diagram agrees with the updates, and a real typed acceptance covers this version and scope. Save the acceptance receipt and intended tree updates, then run update_views.py to validate them before editing implementation files. If recording or validation fails, report and resolve the failure before implementation; do not claim the trace was persisted. Keep the later result and any PR description consistent with the actual saved diff. Ordinary capture and reasoning endorsement retain their existing rules without this project-change approval gate.

Next step

Recommend one useful action or inquiry without implying it was performed. Keep the basis tied to the user's aim and current reasoning. If the recommendation comes only from a handoff or task order, say so. Call something a constraint hypothesis only when the reasoning supports that description.

**Type: Next step**

**Next:** [One concrete action or focused question.]

**Why:** [The relevant reasoning with its tree, node kind or link relation and standing, and the uncertainty or dependency that makes this useful now.]

**What this resolves:** [The decision or uncertainty the answer would affect.]

**State:** [Relevant save result and standing, or no change; the recommended action has not been performed.]

[Optional quieter alternative or diagram, when useful. End with the one invitation that needs a reply.]

Do not manufacture a tree update merely to recommend a next step. Capture any new substantive reasoning normally and report what was saved. If the recommendation is later requested as implementation, issue its Change proposal before editing.

Change result

Use this for the final implementation report. Carry forward the proposal's reasoning served and replace intended updates with the actual updates. State any difference from the proposal plainly.

**Type: Change result**

**Changed:** [The implemented behavior and where to inspect it.]

**Reasoning served:** [The same relevant IDs with their trees, kinds or relations, meanings and standings, revised if the actual scope changed.]

**Tree updates:** [Actual node/link/backlog changes with each item's tree, kind or relation and resulting standing, with a link to the saved reasoning.]

**Acceptance:** [Proposal ID and revision, human identity and recording time, with a link to the saved receipt.]

**Validation:** [Checks completed, their results and remaining uncertainty.]

**Saved:** [Where the work is saved and its delivery state: working files, commit or PR as applicable. Implementation completion does not imply accepted reasoning.]

Before sending, compare the tree updates with the saved state and actual diff. A brief “fixed, tests pass” omits the required trace. Do not describe working-file edits as committed or published.

When delivering through a PR, show visible rendered Reasoning changes diagrams and collapse the complete checked Tree updates list. Carry forward the saved proposal ID, revision and participant under Accepted change proposals, alongside reasoning served and validation. Read pull-requests.md, generate with check_pr_trees.py --suggest --format markdown, run the check against the PR base and inspect the rendered description before reporting completion. Do not ask for repeat acceptance of an unchanged, already-recorded scope; a material expansion needs a revised proposal and fresh acceptance before implementation. PR review approves the resulting implementation for integration and remains separate from approving the intended work or endorsing reasoning.