diff --git a/docs/behavior-validation.md b/docs/behavior-validation.md index 591c198..30d98f3 100644 --- a/docs/behavior-validation.md +++ b/docs/behavior-validation.md @@ -69,7 +69,8 @@ For each example ask: What is the result? What does it mean for the goal? What f | Situation | Expected decision | Instructions to inspect | |---|---|---| -| A small change has a clear goal, known entrypoint, and suitable existing checks. | Stop planning research when the meaningful decisions are settled. Give a short actionable plan, no interview or blanket verifier offer, and direct the human to the native implementation action. | [Planning](../skills/plan-work/SKILL.md) | +| A small change has a clear goal, known entrypoint, and suitable existing checks. | Stop planning research when the meaningful decisions are settled. Give a short actionable plan, no interview or blanket verifier offer, and direct the human to the native implementation action. Omit the second-order note. | [Planning](../skills/plan-work/SKILL.md) | +| A material change affects architecture, a breaking contract, several surfaces, or schema and deploy. | Note second-order effects in one line each where relevant: caller impact, data or migration, deploy and rollback, and security or auth. Mark speculation as speculation. | [Planning](../skills/plan-work/SKILL.md) | | A product choice changes the expected behavior or scope. | Ask the decisive question with a reasoned recommendation before dependent work; do not turn routine technical choices into approval gates. | [Planning](../skills/plan-work/SKILL.md), [working agreement](../references/workflow.md) | | Native implementation has only the approved plan and assignment. | The plan carries reporting expectations and the host's review invocation. The executor reports actual checks and recommends a separately commissioned Review, without claiming it passed. | [Planning](../skills/plan-work/SKILL.md), [implementation handoff](manual-workflow.md#plan-and-implementation), built host instructions | | A required check failed, although other checks passed. | State the failed behavior, consequence, and named correction. Recommend the host's correction invocation without starting it or claiming completion. | [Review](../skills/review-work/SKILL.md), CSV export example | diff --git a/docs/manual-workflow.md b/docs/manual-workflow.md index 946d2b4..de02908 100644 --- a/docs/manual-workflow.md +++ b/docs/manual-workflow.md @@ -38,7 +38,7 @@ For example, in Codex: In Cursor, replace `$plan-work` with `/plan-work`. -The agent inspects your project and prepares a plan. It explains the intended result, scope, important decisions, risks, and checks. It also reads relevant saved project lessons and checks that they still apply. Questions should resolve real uncertainty; a clear, small task should produce a proportionate plan. +The agent inspects your project and prepares a plan. It explains the intended result, scope, important decisions, risks, and checks. It also reads relevant saved project lessons and checks that they still apply. Questions should resolve real uncertainty; a clear, small task should produce a proportionate plan. When the change is material (architecture, a breaking change, several surfaces, or schema and deploy), the plan also notes second-order effects in one line each where relevant: caller impact, data or migration, deploy and rollback, and security or auth. Speculation is marked as speculation. A routine fix or small plan leaves that note out. For this example, look for checks covering filtered orders, visible columns, and empty exports. Resolve important choices before approving the plan. Planning may also offer optional [methods or verifier work](project-improvement.md). diff --git a/skills/plan-work/SKILL.md b/skills/plan-work/SKILL.md index ec18f68..d123f00 100644 --- a/skills/plan-work/SKILL.md +++ b/skills/plan-work/SKILL.md @@ -9,7 +9,7 @@ Read the [working agreement](../../references/workflow.md). A natural-language r Stop investigating once the goal, boundaries, key interfaces, and suitable checks are clear enough for implementation. Ask about consequential human choices with a reasoned recommendation. A clear assignment needs no interview or advance design of routine implementation details. -Explain the goal and benefit, observable success criteria, scope and exclusions, material risks and dependencies, key decisions, and appropriate checks. Include files, interfaces, commands, examples, or sequencing where they remove ambiguity. A small change may need only a few paragraphs. +Explain the goal and benefit, observable success criteria, scope and exclusions, material risks and dependencies, key decisions, and appropriate checks. Include files, interfaces, commands, examples, or sequencing where they remove ambiguity. A small change may need only a few paragraphs. When the change is material (architecture, a breaking change, several surfaces, or schema and deploy), note second-order effects in one line each where relevant: caller impact, data or migration, deploy and rollback, and security or auth. Mark speculation as speculation. Omit this for a routine fix or a small plan. Before presenting the plan, settle success criteria, instruction conflicts, permissions, and consequential choices. Give it a descriptive title. Carry the working agreement, [implementation requirements](../../references/implementation-work.md), accepted references, and complete open learning collection into the handoff. In standalone work, direct the human to check the plan and start implementation, then commission Review. In expressly commissioned Auto-Work, Light waits for plan approval; Dark can continue within the human goal assignment. Neither mode resolves consequential missing choices by assumption.