he-plan

Hard Eng Plan

• Output = saved PLAN.md: ready plan + UX reference when applicable + baseline evidence + execution recommendation + authorization boundary, or explicit blocking decisions. Planning may produce the plan, research + isolated previews; production implementation waits for readiness + authorization.
• Context = Hard Eng workflow. Reuse current repository evidence + settled decisions; load Research or Codebase Design only when needed.

Routes

Select from the user's intent + actual scope, not a keyword alone. Existing ready plan → continue within its authorization; material change → reopen only the affected decision.

flowchart TD
  T{Planning need} -->|Explicit Wayfinder / large unclear effort| W[references/wayfinding.md]
  T -->|Small clear change| S[Compact PLAN.md]
  T -->|Feature / substantial or multi-session work| P[templates/PLAN.md]
  W -->|Direction resolved; implementation requested| P
  S --> U{Visible change?}
  P --> U
  U -->|Yes| X[references/ux.md]
  U -->|No| R[Readiness + authorization]
  X --> R
  click W "references/wayfinding.md"
  click P "templates/PLAN.md"
  click X "references/ux.md"

Plan + questions

• Tracked evidence = apply publication privacy before writing plans or attaching evidence.
• Small = check decides by script, from the whole branch against its merge base (see README, Plan); a small change needs no plan, but a plan you write is still validated. Never mark a change small yourself.
• Both sizes = PLAN.md; one plan per effort at root or features/<slug>/PLAN.md (filename case-insensitive). Reuse it. Write brief fields + behavior → proof checkboxes, not narrative paragraphs; link detailed evidence instead of copying it. Fill every section; N/A — reason must follow repository facts. Unavailable tools, failed checks + missing proof are blockers, never N/A.
• Questions = inspect repository facts first; ask only user-dependent choices that can change outcome, UX, scope or material risk. Resolve prerequisite choices first; batch independent questions with a recommendation + consequences. Never supply the human's answer or treat silence as approval. Clear request → no ritual interview.
• Setup/adoption/update = follow integration setup for intended services, hosting, existing choices and real host readiness; greenfield imports alone cannot identify future integrations. New Flutter app = Riverpod per Building Flutter Apps.
• Proof = reconcile every material requested behavior + preserved constraint with an intended check + observable expected result in Acceptance + steps; explicitly mark exclusions or blockers. Fill the template's E2E: disposition separately from ux_reference: unchanged appearance does not waive an interaction journey. Use test design + E2E for applicable proof; each user-journey checkbox names its E2E test; outside service → fake from its real responses, tests never call the real one. Ready needs planned feature proof + actual baseline/UX evidence; Complete needs actual feature results. Deployment-only E2E requires Deploy and a configured verifier, never a Merge target that closes before runtime proof.
• Delivery = keep build acceptance local; retain the authorized destination + pending remote proof in Verification for HE Ship. Local Complete precedes shipping. Before UI implementation, retain the actual baseline for the later PR comparison even when planning used a mock; prepare task isolation.
• Flow gaps = for material state, permission, recovery or cross-system behavior, inspect existing entry points, relevant branches and success/failure/recovery outcomes before Ready. Reuse existing handlers; resolve consequential unspecified behavior through the questions above and carry the scenarios into acceptance. Settled low-risk work needs no extra walkthrough.
• Uncertainty = for a consequential unverified technical assumption, record current evidence, the cheapest discriminating check + what changes if false. Resolve planning-owned facts through research or an authorized isolated prototype; keep build-dependent details explicit for implementation. Unresolved product choices remain blockers; helper names and low-impact details do not.