# Arch Mini Plan

> Explicitly selected one-pass architecture plan with canonical arch blocks. Use when the user chooses $arch-mini-plan or a selected parent requires it. An ordinary short plan does not select this artifact format, and creating the plan does not activate implementation.

- Skill: `aelaguiz/arch-mini-plan` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/arch-mini-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/arch-mini-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/arch-mini-plan

---


# Arch Mini Plan

Use this workflow only after explicit selection as `$arch-mini-plan` or a
binding task instruction requiring it.

## When to use

- The user explicitly asks for a mini plan or a one-pass architecture plan.
- The task is small or medium-sized, but still benefits from the canonical arch blocks.
- The user wants planning rigor without walking the full research -> deep dive -> external research -> phase plan sequence as separate steps.
- The likely next steps after planning are implementation against the same doc via `miniarch-step` or `arch-step`, then docs cleanup via `arch-docs`.

## When not to use

- The task is a tiny feature or improvement that should run through `lilarch`.
- The task clearly needs staged full-arch execution, long-running plan shaping, or full-arch implementation/audit work. Use `arch-step`.
- The problem is primarily a bug/regression investigation. Use `bugs-flow`.
- The path is intentionally open-ended or hypothesis-driven. Use native goal mode or `north-star-investigation`.

## Non-negotiables

- This mode is planning-only. Do not modify code here.
- Keep one canonical `DOC_PATH` as the source of truth.
- Write the compact Scope and Simplicity Contract from
  `references/artifact-contract.md`. Initial architecture may include only the
  smallest evidenced same-contract convergence closure; sign it off at the ready
  verdict. After that verdict, only explicit human approval expands scope.
- Use the same canonical arch markers and compatible section shapes that `arch-step` expects.
- Keep the phase plan tight: usually 1-2 phases, optionally 3 if cleanup truly needs its own pass.
- Escalate when human-authorized or pre-approval convergence work genuinely
  exceeds a compact plan, or when decisions remain unresolved. Do not escalate
  merely because the planner imagined adjacent work.
- Ask questions only when repo/docs/tools cannot answer them.
- When the changed behavior is agent- or LLM-driven, inspect prompt surfaces, native model capabilities, and existing tool/file/context exposure before designing.
- For agent-backed systems, prefer prompt engineering, grounding, and native-capability use before new harnesses, wrappers, parsers, OCR layers, or scripts.
- If mini mode still concludes that custom tooling is needed for agent-backed behavior, say why prompt-first and capability-first options were insufficient.
- If the real lever is prompt repair, say so plainly and recommend `prompt-authoring` instead of inventing deterministic scaffolding.
- When source material includes prompts, agent instructions, or other instruction-bearing doctrine, preserve explicit structure by default instead of silently condensing it.
- External guidance is optional and narrow. Do not turn mini mode into hidden full-arch research.

## First move

1. Read `references/artifact-contract.md`.
2. Read `references/shared-doctrine.md`.
3. Read `../_shared/scope-and-convergence.md`.
4. Read `references/fit-and-escalation.md`.
5. Resolve `DOC_PATH` and read it fully.
6. Verify the North Star and scope are coherent enough to plan against.
7. Read `references/quality-bar.md`.
8. Read `references/one-pass-plan.md`.
9. Then write the canonical arch blocks in one pass.

## Workflow

1. Confirm this is the right mode:
   - smaller task
   - still needs real architecture grounding
   - not a `lilarch` fit and not an immediate staged full-arch execution fit
2. Gather the minimum evidence needed:
   - internal ground truth and reusable patterns first
   - external guidance only if correctness depends on it
3. Update the canonical blocks together:
   - research grounding
   - current architecture
   - target architecture
   - call-site audit
   - phase plan
4. Stop with a clear "ready to implement" verdict and the recommended next move.

## Output expectations

- Update `DOC_PATH` only.
- Keep the console summary short:
  - North Star reminder
  - punchline
  - which blocks changed
  - any "too big for mini mode" warning
  - exact next move, usually `miniarch-step implement`, `miniarch-step reformat`, or `arch-step reformat`, with `arch-docs` as the later full-arch docs-cleanup handoff after clean code audit

## Reference map

- `references/artifact-contract.md` - canonical mini-plan artifact, required blocks, status rules, and handoff contract
- `references/shared-doctrine.md` - evidence, question policy, SSOT rules, and anti-fallback discipline
- `references/fit-and-escalation.md` - concrete fit examples, non-fit examples, and exact escalation rules
- `references/one-pass-plan.md` - the one-pass planning workflow and write order
- `references/quality-bar.md` - strong vs weak bars for the blocks mini mode owns