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.

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.

For every mechanism-sized topology or reliability decision, name the approved requirement, constitution rule, external contract, reproduced failure, or reachable derived risk it serves. Do not manufacture coordination, exactly-once semantics, fencing, generations, new identities, timers, cross-restart durability, or similar machinery as generic hardening; apply the deletion test and remove the mechanism when its requirement disappears.

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

Compare plausible designs 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. For each mechanism, name the reproduced failure or live consumer it serves and apply the deletion test.

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.
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.

6. Decompose for execution without losing global context

Use skills/decompose-gates to define meaningful lanes when parallel execution is actually possible. Each lane owns a complete responsibility and an independently deciding check; do not create microtasks, overlapping seam authorities, or horizontal layers that cannot be validated before later activation.

Every meaningful implementation, review, and QA lane must read the complete approved plan unless it is already present in active context. Its lane brief then stays concise and self-contained: goal, ownership, exact paths/symbols, dependencies, acceptance checks, validation, expected output, permissions, and stop/fallback conditions. Reference the on-disk plan rather than pasting it or inheriting the full parent transcript; use minimal inherited conversation context.

7. Review the draft before approval

Before presenting a draft, attack it once at the plan-design phase:

• re-derive whether it solves the real intent;
• look for missing consumers, dependencies, removals, failure/recovery behavior, and half-wired verticals;
• test whether any proposed mechanism survives the deletion test;
• check split-brains, wrong-layer ownership, compatibility provenance, test value, and scope creep;
• ensure every required outcome has a deciding check and no task can be marked complete from code presence alone.

Select only the reasoning lens that addresses the plan's load-bearing uncertainty—such as hardest-constraint-first analysis, a pre-mortem, reversibility, or a fresh-executor ambiguity pass. Do not run every lens or create a separate report for each.

This is the plan's design review, not a mandatory second preflight during implementation. Resolve findings in the draft, surface remaining user decisions, and present the plan as DRAFT. Only explicit user approval establishes it as the APPROVED execution contract.

8. Preserve authority during execution

Once approved, the plan's required outcomes, ownership, interfaces, compatibility obligations, removals, user flows, exclusions, and acceptance criteria are authoritative. Implementation agents:

• read and execute the complete approved plan;
• may update only designated execution status and evidence;
• use best judgment only where the plan intentionally leaves implementation detail open;
• do not silently simplify, reinterpret, expand, substitute, or redesign approved requirements;
• do not run a separate deep plan review before implementation; orient to current load-bearing anchors and begin.

Keep the approved contract stable and the execution ledger mutable. The orchestrator owns overall status, cross-lane dependencies, finding disposition, amendment records, and final verdict; lane agents update only their owned reports/status evidence. After compaction, interruption, reassignment, or an approved amendment, reread the plan's current contract/pivot and mutable execution state only when those contents are no longer active or may have changed.

Use these execution states:

• PLANNED
• IN_PROGRESS
• IMPLEMENTED_NOT_VERIFIED
• VERIFIED_COMPLETE
• PARTIAL
• BLOCKED
• AMENDMENT_REQUIRED
• SUPERSEDED_BY_APPROVED_AMENDMENT
• NOT_APPLICABLE with rationale

Never use SUPERSEDED_BY_EVIDENCE: evidence may challenge the plan but does not authorize changing it.

9. Amend rather than silently deviate

If primary evidence shows an approved requirement is unsafe, contradictory, impossible, based on a materially changed contract, or unable to serve the approved intent:

1. pause the affected work;
2. record the exact evidence and affected requirements;
3. explain why ordinary implementation discretion cannot resolve it;
4. propose the smallest coherent amendment and its impact on dependencies, validation, and completed work;
5. ask the user to approve, reject, or redirect it;
6. resume only after approval, recording SUPERSEDED_BY_APPROVED_AMENDMENT and preserving the amendment history.

Continue unaffected independent work only when it cannot prejudge the user's amendment decision. Material ambiguity follows the same stop-and-clarify path; unrelated discoveries are reported without expanding the plan.

When corrections accumulate until the document no longer reads as one coherent contract, propose a user-authorized REPLACE that regenerates it while explicitly preserving, changing, or retiring still-applicable material decisions rather than layering more amendments onto a contaminated document.

10. Define completion from evidence

No phase, lane, or plan is complete because files exist, code compiles, a checkbox changed, or an agent said “done.” VERIFIED_COMPLETE requires the implementation owner and reachable wiring, required removals/absence, meaningful RED → GREEN evidence for behavior changes, risk-appropriate broader validation, live QA for user-visible/environment-dependent behavior when runnable, and explicit residual risk.

For plan-completeness review, use skills/happier-review and its references/plan-completeness.md. The reviewer grades implementation against the approved contract; it does not replace that contract.

When the user explicitly asks to execute or resume the approved plan, hand off to skills/happier-implement-plan; do not extend this authoring skill into a competing execution workflow.