Labsco
microsoft logo

writing-plans

✓ Official★ 4,933

by microsoft · part of microsoft/fluidframework

Once it is settled what to build, this turns that into a written plan detailed enough for somebody who has never seen the codebase to work from, testing included.

WHEN YOUR AGENT SHOULD USE IT

A QUICK BOUNDARY

USE FOR

  • Turn a finished design into bite-sized implementation tasks with exact file paths to touch.
  • Write a test-first testing plan that checks real behavior instead of mocks or data types.
  • Note backward-compatibility concerns and edge cases before implementation starts.
  • List open questions an engineer needs answered before starting the work.

DO NOT USE FOR

  • Doesn't write the implementation code itself; plans describe what to build, not the code.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

CRITICAL. Add the following steps to your Todo list using TodoWrite:
  • Read the 'Guidelines'.
  • Create a comprehensive plan that a senior engineer can follow. Any absolute paths in your plan MUST take into account any worktrees that may have been created
  • Think about backwards compability. Add any notes to the plan.
  • Think about edge cases. Add them to the plan.
  • Think about questions or areas that require clarity. Add them to the plan.
  • Emphasize how you will test your plan.
  • Present plan to user.

Guidelines

Overview

Create a comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD.

Assume they are a talented developer. However, assume that they know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Do not add code, but include enough detail that the necessary code is obvious.

Do not write a file to disk unless explicitly asked.

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Test Section

Every plan MUST have a test section. This should be written first, and should document how you plan to test the behavior.


**Testing Plan**

I will add an integration test that ensures foo behaves like blah. The
integration test will mock A/B/C. The test will then call function/cli/etc.

I will add a unit test that ensures baz behaves like qux...

You should end EVERY testing plan section by writing:

NOTE: I will write *all* tests before I add any implementation behavior.

Your tests should NOT contain tests for datastructures or types. Your tests should NOT simply test mocks. Always test actual behavior.

For each test, follow this checklist: - Ensure that the test does not just test mocks. If it does, remove the test and try again. - Ensure the test does not test implementation detail. If it does, rewrite the test so that it tests boundary behavior. - Ensure the test does not test data structure format or types. If it does, remove the test and try again. - Ensure the test does not test for removed behavior. For example, if some behavior has been deprecated, do not write a test that simply confirms the behavior no longer works. - Evaluate if the test treats the interior of the test boundary as a blackbox. You should not know anything about interior variables, function calls, or control flow.

Every plan MUST end with this footer:

**Testing Details** [Brief description of what tests are being added and how they specifically test BEHAVIOR and NOT just implementation]

**Implementation Details** [maximum 10 bullets about key details]

**Question** [any questions or concerns that may be relevant that need answers]

---