Happier Plan

Happier Plan

Create a repository plan only on an explicit current-user request. Planning is a human-controlled product/design decision, not an agent-selected prerequisite. Do not invoke this skill to implement an existing plan, update ordinary execution status, review completed work, or create an internal ephemeral checklist.

1. Establish authorization and mode

Classify the explicit request as one of:

• CREATE: author a new repository plan;
• REFINE: materially change a draft or approved plan as the user requested;
• REPLACE: supersede an existing plan with a user-requested successor;
• AMEND: record a user-approved change to an approved execution contract.

If the user did not explicitly request one of these, do not create or materially edit a plan file. A reviewer or implementation agent may recommend a plan/amendment, but only the user can authorize creating it or changing its approved contract. A successor references its predecessor and explicitly preserves, changes, or retires still-applicable material decisions; do not mechanically transcribe historical tasks, findings, or markers.

Plan authoring does not authorize implementation. If the user asked only for a plan, stop after presenting the draft. If the user requested both planning and implementation, present the plan for approval before treating it as the execution contract unless the user explicitly waived that checkpoint.

2. Recover the real intent before designing

State the outcome beneath the literal request:

• user-visible or operational problem;
• invariant or capability that must hold afterward;
• affected users/components and real workflows;
• explicit exclusions and non-goals;
• compatibility, security, performance, accessibility, platform, and rollout constraints that are actually reachable;
• evidence that will distinguish success from a plausible incomplete implementation.

Separate observed facts, derived conclusions, assumptions, and unresolved user decisions. Resolve decision-material ambiguity before finalizing a design; do not bury it as an implementation detail.

For cross-device or cross-runtime work, identify separately the client surfaces, canonical authority and executor, transport, durable state and lifetime, behavior while the authority is unavailable, and required consistency. Do not infer any one of these contracts from another.

Before decomposing work, derive the plan backward from the intended outcome:

1. state the user-visible, operational, compatibility, and architectural truths that must hold when the work is complete;
2. identify the canonical owners or artifacts that establish each truth;
3. identify the real entry points, consumers, wiring, migrations, removals, and compatibility paths required to make those owners authoritative;
4. identify the few links whose failure would be most damaging or least visible;
5. attach deciding evidence that observes each truth at the outermost practical contract surface.

Do not create a separate truth/artifact matrix when the plan's intent, target-state, execution, migration, QA, and completion sections can express this mapping.

Include a constraint only when it excludes or materially changes a plausible implementation. Convert vague qualities such as “robust,” “clean,” “premium,” or “scalable” into an observable contract, deciding principle, or acceptance signal; otherwise omit the decorative wording.

Do not promote an architectural possibility, speculative future consumer, generalized reuse opportunity, another proposed mechanism, or unsupported robustness/scalability target into a requirement. Establish requirements from an approved outcome, constitution rule, external contract, reproduced failure, or reachable derived risk; mechanism selection and the recursive deletion test belong in the target-design step below.

3. Investigate the current system

Before selecting the target shape, inspect enough current code and evidence to name:

• the canonical owner and why it owns the behavior;
• real entry points, callers, producers, consumers, readers, and writers;
• current schemas, persistence, lifecycle, feature decisions, compatibility seams, and external contracts;
• existing tests, testkits, live QA surfaces, and platform-specific paths;
• existing, similar, competing, legacy, bypass, or split-brain implementations in the affected corridor;
• overlapping active plans/programs and their Supersedes:, Extends:, or Consumes: relationships;
• the two or three highest-risk or quietest failure points.

Search broadly enough to establish these facts, then stop. Do not turn optional confirmation into an unbounded research phase. Use current primary evidence for changing external contracts and released artifacts/tags for compatibility obligations.

4. Select the smallest coherent target design

Apply root Scope-preserving solution economy at design time: preserve the complete feature outcome, challenge unsupported machinery rather than the feature itself, and fold behavior into the canonical owner before proposing another path.

When the work changes ownership, crosses packages, introduces persistence/concurrency, changes a public contract, or adds a protocol, state machine, registry, table, lease, credential, generation, gate, or parallel path, write the intended caller-visible usage first and compare plausible designs from what callers should know. For each mechanism, trace its justification through proposed dependencies to an approved outcome, required invariant, released or external contract, reproduced failure, or reachable material risk. Apply the deletion test recursively: remove the mechanism and everything that exists only to support it, then name the required outcome that fails. Another proposed mechanism, future consumer, generalized reuse, or architectural completeness is not a terminal justification.

Treat every new limit, quota, timeout, retry budget, or guard as product behavior. Name the resource or contract it protects, derive it from that boundary rather than a nearby number, and define what happens when it fires; preserve useful valid data when safe rather than turning a safety backstop into an ordinary product filter.

Apply scope-preserving solution economy only after fixing the complete target boundary. For a mechanism-sized decision, consider whether the outcome can be satisfied by adding nothing, correcting or consolidating the canonical owner, using the language/standard library, using a platform-native capability that satisfies every affected surface, using an existing package-owned dependency, or finally adding a new custom mechanism. Choose the earliest option that satisfies the complete contract and minimizes total lifetime complexity; never use this ordering to reduce required behavior, migration, removals, compatibility, UX, security, accessibility, platform support, testing, or validation.

Be able to name why a materially simpler plausible alternative cannot satisfy the contract. Record that reasoning only when it preserves a decision, constraint, or rejection that a later implementer or reviewer would otherwise have to rediscover; do not create a mandatory alternatives table or item-level justification ceremony.

Classify every material choice as approved and binding, intentionally delegated to implementation discretion within named constraints, or deferred/excluded. Do not leave a choice implicitly open when different interpretations would change ownership, interfaces, compatibility, migration, security, UX, or acceptance.

Call out a choice as difficult to reverse only when changing it later requires a concrete migration, destructive operation, compatibility break, external coordination, or public-contract transition. Record its undo path or approval consequence before implementation. Do not label large but ordinary refactors irreversible or add a gate merely to simulate reversibility.

Choose the design that realizes the full intent with:

• one canonical owner per decision;
• a consumed vertical from real entry point through owner to observable output;
• explicit invariants and fewer invalid states;
• reuse/refinement/removal of existing paths rather than a similar-but-different implementation;
• the narrowest compatibility transition justified by reachable released/predecessor combinations;
• no dormant replacement spine, speculative extensibility, unnecessary gate, or test matrix manufactured by the plan itself.

Do not optimize for the smallest diff when a coherent owner-level correction is broader. Do not solve unrelated corridor debt unless it is required to avoid a competing active owner or to make the authorized outcome correct. Report adjacent defects without manufacturing a transfer ledger; absorb another program's scope only with explicit user approval.

5. Write a self-contained execution contract

Plans may be large when the domain requires it. Do not impose arbitrary line, phase, or task-count limits; every section must earn its place by preserving a decision, fact, invariant, dependency, or deciding check that a later zero-context implementer would otherwise have to rediscover.

Create new plans under the repository's existing .project/plans/ convention, using a descriptive stable filename or the existing program folder; refine an existing plan in place unless the user requested a successor. The plan must contain:

1. Identity and state: title, path, DRAFT status, contract revision, approval/amendment record, owner/user decision points, relevant plan relationships, and dated evidence basis where applicable. Status-only execution updates do not change the contract revision.
2. Intent: problem, target outcome, users/flows, non-goals and plan-specific forbidden mechanisms, material outcome truths, outermost success evidence, and stable IDs for material requirements and invariants in substantive plans.
3. Current-state evidence: canonical owner, affected corridor, existing split-brains, contracts, compatibility provenance, and relevant tests/harnesses with exact paths/symbols.
4. Target state: final ownership, data/control flow, interfaces, invariants, file/module placement, migrations/removals, and retained compatibility seams with removal conditions.
5. Decisions: selected design; choices that are approved, intentionally delegated within constraints, or deferred/excluded; concrete one-way decisions and undo consequences; unresolved material user decisions; rejected alternatives when useful; and why the selected design removes more total complexity or risk. Reference decision evidence by path instead of creating item-level ratification bureaucracy.
6. Execution units: ordered consumed verticals or independently verifiable gates, exact scope/ownership, dependencies, external/runtime preconditions not guaranteed by ordering, concrete implementation outcomes, named required deletions, deciding checks, and traceability to the material requirement/invariant IDs they satisfy. Do not manufacture a precondition for ordinary code dependencies.
7. QA and validation: risk-weighted automated and live scenarios covering every materially affected flow, relevant edge/failure/recovery states, accessibility/performance/platform dimensions, and reachable compatibility directions without irrelevant Cartesian expansion. Plan feature QA against the current moving source and existing development stack; never introduce a frozen release representation, archive-production step, local package-installation gate, or publication proof as feature-completion evidence.
8. Completion contract: observable acceptance criteria at the outermost practical contract surface, negative requirements, evidence required for each gate, what explicitly prevents completion, and an auditable mapping showing that every material requirement/invariant has deciding evidence. Imports, registrations, types, file existence, and internal proxies are supporting evidence rather than completion when real behavior is runnable.
9. Execution tracking: mutable status/evidence area separate from the approved design contract.

Use exact paths, symbols, contract shapes, and target filenames when established by evidence. When a detail is intentionally open, say what constraint governs the implementer's choice; do not invent false precision. Reference generic AGENTS.md, DESIGN.md, skills, large logs, and bulky evidence by path with a concise digest instead of copying them into the plan.