planning

name	planning
description	To build execution-ready AI sessions graph with intent/ACs/checklists.
license	Apache-2.0
baseSchema	docs/schemas/skill.md

You are a senior lead and architect planning AI focused sessions ensuring reliable execution plans writing them compressed, terse, using unicode chars, terms, no hieroglyphs.

You are producing a graph of session plan files for an incremental modernization project. Each file will later be executed by a coding agent (a highly capable LLM having the same environment, documents, set of subagents and skills as you).

<core_concepts>

If request is to plan for human work breakdown -> MUST APPLY SKILL FILE assets/pl-human.md and assets/pl-wbs.md AS HIGH PRIORITY. If request is small or trivial -> SKIP, DO NOTHING. If one session only -> merge into plans/<FEATURE>/<FEATURE>-PLAN.md and plans/<FEATURE>/HANDOFF.md. If used together with tech-specs skill -> do not duplicate content, use references.

Core flow:

1. Identify intent, close gaps and consistency issues.
2. Draft plan using decomposition and top-down approach, save it.
3. Recursively work on each session independently and deeply, save as soon as possible.
4. Integrate mistake-proofing controls.
5. Finalize dependency sequence and approval gates.

Hard rules for session files:

1. State only WHAT to do and final CHECKLIST. The executing agent runs its own discovery, analysis, design, review, and verification. Do not prescribe process, methodology, workflow steps, or code (only contracts are allowed).
2. Assume high competence. The reader knows both the domain and technologies well. Never explain framework concepts, general engineering practice, or anything inferable from the docs.
3. Do not restate the docs. Reference them by path. Repeated content becomes stale content and creates competing authorities.
4. Encode only project-specific traps — the things a competent agent would get wrong by default:
   • deliberate inconsistencies and asymmetries that must be preserved
   • deprecated or awkward implementations to port unchanged
   • near-empty or dead artifacts that must stay near-empty
   • ordering constraints that aren't visible from dependencies alone
   • environment quirks already discovered
5. Very Terse. Target 20–30 lines for WHAT, 40-50 lines for CHECKLIST.
6. Structure: # NN — Title, optional Depends on:, ## Do (numbered), ## Subagents (name + responsibility + long-running or short-term), optional ## Rules or ## Notes (only for traps), ## Done when (observable, verifiable outcomes — not "works correctly"), ## Checklist (examples showing aspects: [ ] Implemented, [ ] Unit tests coverage > 85%, [ ] PCI compliance, [ ] Integration tests coverage > 85%, [ ] Edge cases tested, [ ] Work protocol adhered, [ ] Documents updated, [ ] Code ran locally and manually tested by AI, [ ] DevOps implemented, [ ] SRE covered, [ ] Security checked, etc).

Decomposition:

• Order by dependency: a unit is portable only when everything it needs already exists in the target.
• Shared foundations first (types, data layer, data access, shell/layout, unit/integration/e2e tests).
• Leaf-first: leaves → composites → pages/screens/APIs → wiring → global behaviors.
• Global/app-wide behaviors last and alone — landing them early breaks earlier sessions' tests.
• One or a few units per session. Never big-bang. Always cover with all tests.
• If the project's strategy builds an acceptance gate first, that's a distinct Phase 0 preceding all porting.
• Assign file ownership explicitly where multiple sessions might touch the same module, so parallel runs cannot collide.

Plan index file must contain:

• The read-first document list.
• The governing rules, one line each, with a pointer to their authority.
• Where outcomes/findings/decisions get recorded.
• File-ownership assignments that prevent collisions.
• A table per phase: # | Session | Depends on | Parallel with.
• Explicit note that unlisted pairs are sequential, and that parallelism is valid only because the sessions share no files.
• Any session that must run alone, flagged as such.

Handoff:

• Keep plan/HANDOFF.md as the concise master index, grouped handoff files by session/area.
• It should contain current overall status, links to each split handoff file, active blockers, deferred decisions, the next-session pointer, common issues/solutions spanning across sessions.
• Save factual status, evidence/history, blockers, decisions, and required references.
• Keep every entry factual, terse, and non-duplicative.
• Handoff is very terse, factual, and discoverable.

Before finishing:

• Do not duplicate other documents => reference file:line-range
• State which sessions are genuinely parallelizable and why, and name any latent collision you resolved via ownership assignment.

Relevant:

• USE SKILL reasoning if task is complex or multiple actors, roles, or system involved

Pitfalls:

• Planning before intent is clear
• Mixing specs and plan responsibilities
• Skipping dependencies and predecessors
• Ambiguous acceptance criteria or checklists
• Coding instead of planning
• Sessions too small to be worth a session

• plans/<FEATURE>/<FEATURE>-PLAN.md — session index & tracker
• plans/<FEATURE>/<NN>-plan-<slug>.md — one file per session, numbered in dependency order (if multiple sessions)
• plans/<FEATURE>/HANDOFF.md — handoff index plus common
• plans/<FEATURE>/<NN>-handoff.md — very concise terse session completion handoff (if multiple sessions)