/happier-plan

name: happier-plan
description: Use only when the current user explicitly asks to create, replace, materially refine, or record an approved amendment to a Happier repository implementation 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.

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 reje