diff --git a/docs.json b/docs.json index 61de6b4..2a4016d 100644 --- a/docs.json +++ b/docs.json @@ -81,6 +81,7 @@ "group": "Collaboration", "pages": [ "plans/collaboration/sharing", + "plans/collaboration/checks", "plans/collaboration/reviews", "plans/collaboration/team-visibility" ] diff --git a/images/plan-checks-menu.png b/images/plan-checks-menu.png new file mode 100644 index 0000000..f360fc4 Binary files /dev/null and b/images/plan-checks-menu.png differ diff --git a/plans/collaboration/checks.mdx b/plans/collaboration/checks.mdx new file mode 100644 index 0000000..983cfb1 --- /dev/null +++ b/plans/collaboration/checks.mdx @@ -0,0 +1,47 @@ +--- +title: "Plan Checks" +description: "Run one-click quality passes over a plan before any code is written." +--- + +A plan is where the real decisions live, and a bad one is far cheaper to fix there than in a pull request. Checks are one-click passes over the current plan: some tighten it for you, some hand back a list of problems for you to decide on. + +## Running a check + +Open the checks menu from the editor controls — the button is labelled **Run plan check**. On a narrow screen it sits in the header's overflow menu as **Run a check**. + + + The checks menu open over a plan, listing each check with its description and an action tag reading Edits plan, Reviews in chat, or Adds section + + +Each entry in the menu shows the check's name, what it looks for, and a tag saying what it will do to your plan. Choose one to start its own chat thread, named after the check. The agent reads the current plan before it does anything else. + +## What a check will do to your plan + +The tag next to each check tells you how far it goes: + +- **Edits plan** — the check rewrites the plan in place. +- **Reviews in chat** — the check replies in the thread with a numbered list of findings and asks which ones you want applied. It does not touch the document until you answer. +- **Adds section** — the check writes what it found into a new section of the plan. + +## Available checks + +| Check | Looks for | Action | +| --- | --- | --- | +| Coherence | Do all sections tell a consistent story? | Edits plan | +| Pre-mortem | Imagine this plan failed — what went wrong? | Reviews in chat | +| Shorten | Cut each task to its core components | Edits plan | +| Extract Human | Separate manual steps from what an agent can code | Edits plan | +| Challenge | Devil's advocate — why might this be wrong? | Reviews in chat | +| Flag Assumptions | Highlight things the plan assumes but hasn't verified | Reviews in chat | +| Backwards Compat | Will this break existing users, APIs, or data? | Reviews in chat | +| Data Migration | Does this touch schemas, migrations, or stored data? | Adds section | +| Security | Check for auth issues, data exposure, injection risks | Reviews in chat | +| Find Related Plans | Discover other plans covering overlapping topics or repos | Adds section | + +## After a check runs + +For a **Reviews in chat** check, reply in the same thread with the findings you want applied, and the agent applies only those. Findings you skip leave the plan untouched. + +Checks that edit the plan or add a section change the document directly, so read the result before you launch agents against it. + +When the plan reads the way you want it to, [request a review](/plans/collaboration/reviews) from a teammate. diff --git a/plans/getting-started/best-practices.mdx b/plans/getting-started/best-practices.mdx index 9fbfe17..361c7ad 100644 --- a/plans/getting-started/best-practices.mdx +++ b/plans/getting-started/best-practices.mdx @@ -40,6 +40,8 @@ Plans are collaborative documents. Use comments in the chat panel to: - Add context you forgot in the initial outline - Get the agent to update tasks based on what you learned during implementation +You can also run [plan checks](/plans/collaboration/checks) to have the agent tighten the plan or report problems in chat before you hand the work to coding agents. + ## When to use multiple plans vs. multiple tasks **Multiple tasks in one plan** when the work is part of a single coherent feature or change. The tasks share context and should be understood together. diff --git a/plans/getting-started/your-first-plan.mdx b/plans/getting-started/your-first-plan.mdx index 46924c7..570b75c 100644 --- a/plans/getting-started/your-first-plan.mdx +++ b/plans/getting-started/your-first-plan.mdx @@ -162,6 +162,8 @@ By the end you'll have a connected repo, a configured agent, and a clear path fr Once the draft is down, use comments to leave feedback or tag teammates for review. Ref can address comments directly, updating the plan based on what you and your team surface. + Run [plan checks](/plans/collaboration/checks) at this point to shorten the plan, stress-test it, or surface the assumptions it hasn't verified. + Split view showing rough notes in the plan editor on the left, and the chat panel on the right where Ref is researching the codebase and writing tasks.