ljw1004 · April 7, 2026 13:59
diff --git a/gistfile1.txt b/gistfile1.txt
 ## HOW TO PLAN A MILESTONE

 If the user asks you to plan a milestone, these are the steps to take.

 1. Read all of PLAN.md (the current document) to learn about the milestone, in the context of past and future milestones. This document lists only the bare essential deliverables and validation steps for each milestone. Read ARCHITECTURE.md to learn the codebase, and LEARNINGS.md for valuable wisdom.
 2. Ask any important initial clarifying questions about the milestone you might have.
  - If you're not asking any questions at all for the entire planning, something's wrong! I know that this file isn't fully specified. There must be important things for you to clarify.
  - It's better to eliminate unknowns in the milestone by discovering facts, not by asking the user. Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable research.
     - **Discoverable facts** (repo/system truth): explore first: Before asking, run targeted searches and check likely sources of truth (configs/manifests/entrypoints/schemas/types/constants). Ask only if: multiple plausible candidates; nothing found but you need a missing identifier/context; or ambiguity is actually product intent. If asking, present concrete candidates (paths/service names) + recommend one.Never ask questions you can answer from your environment (e.g., "where is this struct").
    - **Preferences/tradeoffs** (not discoverable): ask early. These are intent or implementation preferences that cannot be derived from exploration. Provide 2–4 mutually exclusive options + a recommended default. If unanswered, proceed with the recommended option and record it as an assumption in the final plan.
  - When you ask a question, the user doesn't have your context. You must phrase your questions so as to include FULL context, tradeoffs, background, explanation of terms. Don't use jargon. A good question is typically 2-5 sentences long.
  - Questions should where possible offer multiple choices, and your recommendation.
  - Questions should be meaningful; don't include filler choices that are obviously wrong or irrelevant.
  - You SHOULD ask many questions, but each question must: materially change the spec/plan, OR confirm/lock an assumption, OR choose between meaningful tradeoffs. And it must not be answerable by research.
  - Keep asking until you can clearly state: goal + success criteria, audience, in/out of scope, constraints, current state, and the key preferences/tradeoffs.
  - Bias toward questions over guessing: if any high-impact ambiguity remains, do NOT plan yet—ask.
  - Once intent is stable, proceed with implementation planning...
  - Once intent is stable, keep asking until the spec is decision complete: approach, interfaces (APIs/schemas/I/O), data flow, edge cases/failure modes, testing + acceptance criteria, rollout/monitoring, and any migrations/compat constraints.
 3. Have subagents perform milestone-relevant research into these areas and deliver reports. Do these three subagent researchers in parallel.
   - (1) <PROJECT-SPECIFIC RESEARCH>
   - (2) <PROJECT-SPECIFIC RESEARCH>
   - (3) Have subagents research prior PLAN_M{n}.md milestone documents for anything relevant
 4. Flesh out the milestone deliverables and validation steps as needed, if any are missing
   - You should have a focus on validation in everything you do.
   - The validation steps should be about how someone who implements this milestone can validate that their implementation is good
   - I outlined a few tentative validation steps for each milestone, but they're weak, and I expect you to find better validation for each milestone.
   - Make sure to include the basics: typechecker clean and lint clean
 5. Are there better-engineering blockers? If so, bail!
   - The user always wants things done the right way, with clean engineering, good architecture. Never any shortcuts. It's normal that your plan work discovers a structural architectural problem that must be fixed before your plan can proceed.
   - If the architectural problem is small enough to solve, then include that as a phase in your plan. But if it's a major one, worthy of a whole separate plan in its own right, then you should bail, tell the user the problem, and leave them to insert a new milestone specifically for that better engineering.
   - The user is always delighted to hear about better engineering.
 6. Develop your plan for the milestone and write it to a new PLAN_M{n}.md file.
   - A great plan is very detailed—intent- and implementation-wise—so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions. It must be **self-contained**: the implementor will know nothing of your research other than what's in your PLAN_M{n}.md file.
   - The plan must include validation steps, i.e. how someone implementing the plan will validate that they've done so well.
   - If you can verify things up front (e.g. by writing temporary test code or test instrumentation) then do so. Only leave "verify during implementation" for things it's impossible/infeasible to determine during planning, and if so then say why.
 7. You will have several review tasks to do, below, all of them presenting your PLAN_M{n}.md file to Claude and ask for its feedback in various respects. You must launch all these review tasks in parallel, since they each take some time: prepare all their inputs, then execute them all in parallel. You should start addressing the first findings as soon as you get them, rather than waiting for all to be consolidated.
   - (1) Ask for an open-ended review of the plan with no particular guidance, to see what the reviewers find. Ask for all feedback they want to give about the plan, not only blockers or high-priority issues.
   - (2) Ask for a review from KISS perspective: does the plan introduce only the essential minimal new concepts/modules/functions needed to deliver the milestones?
   - (3) Ask for a review from better engineering perspective: is the plan made complicated by poor abstractions in the current codebase? If it'd be better to hold off the plan until we resolve some better-engineering blockers first, the user is eager to know that and is happy to defer the milestone.
   - (4) Ask for a review from perspective of ARCHITECTURE.md -- does the plan fit properly into the existing architecture?
   - (5) Ask for a review from perspective of LEARNINGS.md -- is the plan consistent with all your hard-earned wisdom?
   - You can trust Claude and your subagents have already read AGENTS.md, and are able to do their own autonomous research.
   - In response to feedback, the bar is not "is it a blocker / high risk", but rather "would this feedback improve the correctness/elegance/simplicit/robustness of my plan?" The user is above all keen those things. Even if the feedback is non-blocking, if you think it would improve the plan, then still do it.
   - You're not in a rush to completion. The goal is quality (correctness, elegance, simplicty), and the user is entirely happy if it takes multiple rounds to get there.
   - Do NOT reference previous rounds when you invoke it: Claude does best if starting from scratch each round, so it can re-examine the whole ask from fundamentals. Note that each time you invoke Claude it has no memory of previous invocations, which is good and will help this goal! Also, avoid asking it something like "please review the updated files" since (1) you should not reference previous rounds implicitly or explicitly, (2) it has no understanding of what the updates were; it only knows about the current state of files+repo on disk.
 8. Ask the user any further important clarifying questions you have that arose as a result of your research and Claude-review.
   - Please postpone these questions until the end, after research and Claude-review. That way you will be able to do as much planning as possible without being slowed down by me.
   - Every course-correction the user gives you will likely represent a gap that should be added to LEARNINGS.md or ARCHITECTURE.md. And similarly for many clarifying questions. Please update with these learnings. The goal is so that, if you're asked to develop a plan in future, you won't even need to ask.
   - Please be careful to follow the "learnings decision tree" -- LEARNINGS.md for durable engineering wisdom, ARCHITECTURE.md for things that will apply to <PROJECT> in its finished state, PLAN_M{n}.md for milestone-specific notes
 9. Present the plan for user review and signoff.
   - First, double-check that it is a completely self-contained handoff document.

 Please use the following format for your PLAN_M{n}.md files:
 ```
 # M{n} plan: {title}

 ## Summary
 {brief summary of deliverables+validation for this milestone from PLAN.md, augmented as you see fit}

 ## HOW TO EXECUTE A MILESTONE
 {please include verbatim the content of "how to execute" section of PLAN.md, for the benefit of readers who will read PLAN_M{n}.md but won't read PLAN.md itself

 ## Locked user decisions
 {write out all the decisions that the user made}

 ## PLAN
 {... your plan goes here, in whatever format you see fit. You might include API, algorithms, files changed, testing}

 ## BETTER ENGINEERING INSIGHTS + BACKLOG ADDITIONS
 {what architectural insights you learned, about our codebase or about how things should be done, plus what better engineering has been deferred or will be needed in future}

 ## AI VALIDATION PLAN (how will the Executor of this plan know when it is done?)
 {... what AI will do to validate its work, the "definition of done". This may include typechecking it, running it, running unit and integration tests, creating new tests}

 ## AI VALIDATION RESULTS (how did the Executor show that it was done?)
 {this will be filled during execution}

 ## USER VALIDATION SUGGESTIONS
 {A walkthrough of steps the user can follow, so they can see what you have built}
 ```
	## HOW TO PLAN A MILESTONE

	If the user asks you to plan a milestone, these are the steps to take.

	1. Read all of PLAN.md (the current document) to learn about the milestone, in the context of past and future milestones. This document lists only the bare essential deliverables and validation steps for each milestone. Read ARCHITECTURE.md to learn the codebase, and LEARNINGS.md for valuable wisdom.
	2. Ask any important initial clarifying questions about the milestone you might have.
	- If you're not asking any questions at all for the entire planning, something's wrong! I know that this file isn't fully specified. There must be important things for you to clarify.
	- It's better to eliminate unknowns in the milestone by discovering facts, not by asking the user. Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable research.
	- Discoverable facts (repo/system truth): explore first: Before asking, run targeted searches and check likely sources of truth (configs/manifests/entrypoints/schemas/types/constants). Ask only if: multiple plausible candidates; nothing found but you need a missing identifier/context; or ambiguity is actually product intent. If asking, present concrete candidates (paths/service names) + recommend one.Never ask questions you can answer from your environment (e.g., "where is this struct").
	- Preferences/tradeoffs (not discoverable): ask early. These are intent or implementation preferences that cannot be derived from exploration. Provide 2–4 mutually exclusive options + a recommended default. If unanswered, proceed with the recommended option and record it as an assumption in the final plan.
	- When you ask a question, the user doesn't have your context. You must phrase your questions so as to include FULL context, tradeoffs, background, explanation of terms. Don't use jargon. A good question is typically 2-5 sentences long.
	- Questions should where possible offer multiple choices, and your recommendation.
	- Questions should be meaningful; don't include filler choices that are obviously wrong or irrelevant.
	- You SHOULD ask many questions, but each question must: materially change the spec/plan, OR confirm/lock an assumption, OR choose between meaningful tradeoffs. And it must not be answerable by research.
	- Keep asking until you can clearly state: goal + success criteria, audience, in/out of scope, constraints, current state, and the key preferences/tradeoffs.
	- Bias toward questions over guessing: if any high-impact ambiguity remains, do NOT plan yet—ask.
	- Once intent is stable, proceed with implementation planning...
	- Once intent is stable, keep asking until the spec is decision complete: approach, interfaces (APIs/schemas/I/O), data flow, edge cases/failure modes, testing + acceptance criteria, rollout/monitoring, and any migrations/compat constraints.
	3. Have subagents perform milestone-relevant research into these areas and deliver reports. Do these three subagent researchers in parallel.
	- (1) <PROJECT-SPECIFIC RESEARCH>
	- (2) <PROJECT-SPECIFIC RESEARCH>
	- (3) Have subagents research prior PLAN_M{n}.md milestone documents for anything relevant
	4. Flesh out the milestone deliverables and validation steps as needed, if any are missing
	- You should have a focus on validation in everything you do.
	- The validation steps should be about how someone who implements this milestone can validate that their implementation is good
	- I outlined a few tentative validation steps for each milestone, but they're weak, and I expect you to find better validation for each milestone.
	- Make sure to include the basics: typechecker clean and lint clean
	5. Are there better-engineering blockers? If so, bail!
	- The user always wants things done the right way, with clean engineering, good architecture. Never any shortcuts. It's normal that your plan work discovers a structural architectural problem that must be fixed before your plan can proceed.
	- If the architectural problem is small enough to solve, then include that as a phase in your plan. But if it's a major one, worthy of a whole separate plan in its own right, then you should bail, tell the user the problem, and leave them to insert a new milestone specifically for that better engineering.
	- The user is always delighted to hear about better engineering.
	6. Develop your plan for the milestone and write it to a new PLAN_M{n}.md file.
	- A great plan is very detailed—intent- and implementation-wise—so that it can be handed to another engineer or agent to be implemented right away. It must be decision complete, where the implementer does not need to make any decisions. It must be self-contained: the implementor will know nothing of your research other than what's in your PLAN_M{n}.md file.
	- The plan must include validation steps, i.e. how someone implementing the plan will validate that they've done so well.
	- If you can verify things up front (e.g. by writing temporary test code or test instrumentation) then do so. Only leave "verify during implementation" for things it's impossible/infeasible to determine during planning, and if so then say why.
	7. You will have several review tasks to do, below, all of them presenting your PLAN_M{n}.md file to Claude and ask for its feedback in various respects. You must launch all these review tasks in parallel, since they each take some time: prepare all their inputs, then execute them all in parallel. You should start addressing the first findings as soon as you get them, rather than waiting for all to be consolidated.
	- (1) Ask for an open-ended review of the plan with no particular guidance, to see what the reviewers find. Ask for all feedback they want to give about the plan, not only blockers or high-priority issues.
	- (2) Ask for a review from KISS perspective: does the plan introduce only the essential minimal new concepts/modules/functions needed to deliver the milestones?
	- (3) Ask for a review from better engineering perspective: is the plan made complicated by poor abstractions in the current codebase? If it'd be better to hold off the plan until we resolve some better-engineering blockers first, the user is eager to know that and is happy to defer the milestone.
	- (4) Ask for a review from perspective of ARCHITECTURE.md -- does the plan fit properly into the existing architecture?
	- (5) Ask for a review from perspective of LEARNINGS.md -- is the plan consistent with all your hard-earned wisdom?
	- You can trust Claude and your subagents have already read AGENTS.md, and are able to do their own autonomous research.
	- In response to feedback, the bar is not "is it a blocker / high risk", but rather "would this feedback improve the correctness/elegance/simplicit/robustness of my plan?" The user is above all keen those things. Even if the feedback is non-blocking, if you think it would improve the plan, then still do it.
	- You're not in a rush to completion. The goal is quality (correctness, elegance, simplicty), and the user is entirely happy if it takes multiple rounds to get there.
	- Do NOT reference previous rounds when you invoke it: Claude does best if starting from scratch each round, so it can re-examine the whole ask from fundamentals. Note that each time you invoke Claude it has no memory of previous invocations, which is good and will help this goal! Also, avoid asking it something like "please review the updated files" since (1) you should not reference previous rounds implicitly or explicitly, (2) it has no understanding of what the updates were; it only knows about the current state of files+repo on disk.
	8. Ask the user any further important clarifying questions you have that arose as a result of your research and Claude-review.
	- Please postpone these questions until the end, after research and Claude-review. That way you will be able to do as much planning as possible without being slowed down by me.
	- Every course-correction the user gives you will likely represent a gap that should be added to LEARNINGS.md or ARCHITECTURE.md. And similarly for many clarifying questions. Please update with these learnings. The goal is so that, if you're asked to develop a plan in future, you won't even need to ask.
	- Please be careful to follow the "learnings decision tree" -- LEARNINGS.md for durable engineering wisdom, ARCHITECTURE.md for things that will apply to <PROJECT> in its finished state, PLAN_M{n}.md for milestone-specific notes
	9. Present the plan for user review and signoff.
	- First, double-check that it is a completely self-contained handoff document.

	Please use the following format for your PLAN_M{n}.md files:
	```
	# M{n} plan: {title}

	## Summary
	{brief summary of deliverables+validation for this milestone from PLAN.md, augmented as you see fit}

	## HOW TO EXECUTE A MILESTONE
	{please include verbatim the content of "how to execute" section of PLAN.md, for the benefit of readers who will read PLAN_M{n}.md but won't read PLAN.md itself

	## Locked user decisions
	{write out all the decisions that the user made}

	## PLAN
	{... your plan goes here, in whatever format you see fit. You might include API, algorithms, files changed, testing}

	## BETTER ENGINEERING INSIGHTS + BACKLOG ADDITIONS
	{what architectural insights you learned, about our codebase or about how things should be done, plus what better engineering has been deferred or will be needed in future}

	## AI VALIDATION PLAN (how will the Executor of this plan know when it is done?)
	{... what AI will do to validate its work, the "definition of done". This may include typechecking it, running it, running unit and integration tests, creating new tests}

	## AI VALIDATION RESULTS (how did the Executor show that it was done?)
	{this will be filled during execution}

	## USER VALIDATION SUGGESTIONS
	{A walkthrough of steps the user can follow, so they can see what you have built}
	```
No results found