# Pyramid > Structure memos, recommendations, briefings, and decision documents with the Pyramid Principle. - Skill: `pgoell/pyramid` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add pgoell/pyramid` - Raw SKILL.md: https://api.skillmd.com/api/skills/pgoell/pyramid/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: pgoell (https://skillmd.com/u/pgoell) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pgoell/pyramid --- # Pyramid Skill Multi-phase pyramid-principle skill with a parallel audit panel. Modeled on Barbara Minto's method. --- ## Tool Preference 1. **Subagent dispatch when available and permitted**: to dispatch phase agents (construct in greenfield or restructure mode, opener) and the audit panel (MECE, So-What, Q-A Alignment, Inductive-Deductive). Intake and render run in the orchestrator itself and do not dispatch an agent. 2. **File read tools**: to load prompt templates, the shipped reference, and existing artifacts. 3. **Shell**: for directory creation, file existence checks, and state file read/write. 4. **Progress list**: to surface progress through the pipeline visibly. 5. **File write and edit tools**: for intake.md, audit-summary.md, pyramid.md, and state file management. 6. **User question tool or direct question**: for mode and genre selection, domain-limits gate, MISMATCH routing, and audit re-dispatch overrides. ## Platform Adaptation Use the host platform's equivalent tools without changing the workflow: | Capability | Claude Code | Codex | | --------------------- | ---------------------- | -------------------------------------------------------------------------------------- | | Subagent dispatch | Agent tool | `spawn_agent` only when available and permitted. Otherwise run the phase inline. | | Progress list | TaskCreate, TaskUpdate | `update_plan` | | User questions | AskUserQuestion | Ask a concise direct question, or use the host structured question tool when available | | File reads | Read | shell reads such as `sed`, `rg`, or equivalent file read tools | | File writes and edits | Write, Edit | `apply_patch` or equivalent file edit tools | | Shell | Bash | shell command tool | Where this skill says "Agent tool", "TaskCreate", "TaskUpdate", "AskUserQuestion", "Read", "Write", "Edit", or "Bash", use the mapped host capability. When a platform cannot dispatch subagents for the current request, keep the same artifact boundaries and run each phase inline in the orchestrator. State root is platform-specific. Claude Code uses `~/.claude/projects`. Codex uses `${CODEX_HOME:-~/.codex}/projects` when writable, otherwise create `.codex-skill-state/` under the current working directory. ## Workflow ### Step 1: Determine working directory Resolve working directory in this order: 1. **Explicit flag**: `--dir ./path/to/project/` 2. **Existing artifacts in cwd**: if the cwd already contains any of `intake.md`, `construction.md`, `audit-summary.md`, `opener.md`, `pyramid.md`, treat the cwd as the working directory. 3. **State file lookup**: read `//pyramid-skill-state.json` (where `` is the cwd path with slashes replaced by hyphens, leading hyphen stripped). If an in-flight pyramid is recorded, offer to resume there. 4. **Default**: prompt for a slug, create `pyramid/{slug}-{YYYY-MM-DD}/` in the cwd. ### Step 2: Resolve the active reference Resolution order: 1. **Explicit flag**: `--reference ./path/to/pyramid-reference.md` 2. **State memory**: the state file's recorded reference for this project. 3. **Skill default**: `pyramid-principle-reference.md` shipped with this skill. Resolve its absolute path by locating the directory of this `SKILL.md` file (the skill's own install path) via `Glob` on `**/pyramid/SKILL.md` under the active plugin directory, then take the parent. Surface the active reference in the first response: "Using pyramid reference: {path}". ### Step 3: Determine starting phase Scan the working directory for existing artifacts: - `intake.md` exists → intake phase complete - `construction.md` exists → construct phase complete - `audit-summary.md` exists → audit phase complete - `opener.md` exists → opener phase complete - `pyramid.md` exists → render phase complete Determine the latest completed phase. Present to user: - "I see you have completed phases X. Resume from {next phase}?" - Offer phase-jump option: the user can name any phase to jump to. The user can also pre-empt the dialogue by passing `--phase X` (X ∈ {intake, construct, audit, opener, render}). ### Step 4: Create task list Use the progress list to add one task per phase that will run, plus four sub-tasks for the audit panel. Example for a fresh full pipeline: ``` 1. Phase 1: Intake (mode, genre, domain-limits gate, inputs) 2. Phase 2: Construct the pyramid 3. Phase 3: Audit panel ├── Auditor: MECE ├── Auditor: So-What ├── Auditor: Q-A Alignment └── Auditor: Inductive-Deductive 4. Phase 4: Compose SCQA opener 5. Phase 5: Render pyramid.md ``` For phase-selectable runs, only the requested phases get tasks. Mark each task as `in_progress` when starting and `completed` when the artifact is verified. ### Step 5: Execute phases Dispatch each phase agent via the host subagent tool when supported. The orchestrator injects context into the prompt template. #### Dispatch conventions (apply to every phase) - **`{OUTPUT_PATH}` is always the working directory**, never a file path. Each prompt file appends its own filename. - **Prompt file extraction.** Each prompt file documents the dispatched prompt inside a fenced block under the `**Dispatch:**` header. The simplest robust approach: read the entire prompt file as text, perform placeholder substitution (`{OUTPUT_PATH}`, `{REFERENCE_PATH}`, `{REVIEWER_FEEDBACK}`, `{HANDOFF}`, `{YYYY-MM-DD}`), and pass the full result to the host subagent tool. The dispatched agent ignores the surrounding commentary because the actionable instructions sit inside the visible prompt body. - **`{HANDOFF}` default.** When dispatching `construct-greenfield-prompt.md` in fresh-build or re-dispatch (CRITICAL audit) cases, substitute `{HANDOFF}` with `false`. Substitute `true` only when handing off mid-Mode-D dialogue, or when re-dispatching a Mode-D-built pyramid after a CRITICAL audit. The greenfield prompt's `## Handoff mode` section keys off this value. - **Reviewer feedback injection.** When `{REVIEWER_FEEDBACK}` is non-empty (re-dispatch on a failed audit gate, or after a MISMATCH the user asked to revise), append this standing instruction to the dispatched prompt, regardless of what the prompt template itself says: _"Reviewer feedback is provided above. Read the existing artifact in the output directory, address the specific concerns, and update the file in place rather than starting fresh."_ - **Date substitution.** `{YYYY-MM-DD}` resolves to today's date in ISO format. ## Phase details ### Phase 1: Intake Orchestrator-only, interactive. No Agent dispatch. 1. **Mode.** Ask via AskUserQuestion: _Greenfield (I have a topic and want a fresh pyramid outline) / Restructure (I have an existing draft and want to pyramid-ify it) / Socratic (walk me through it question by question, interactive dialogue)_. Always ask, even if `--mode` was passed; the flag only pre-selects the option. This prevents "surprise wrong mode" failures. 2. **Genre.** Ask via AskUserQuestion: _Memo / Recommendation / Briefing / Strategy doc / Case interview answer / Project proposal / Postmortem / Other (describe)_. Map to the lists in reference section 11. 3. **Domain-limits gate.** If the genre falls in the "Does not work for" list from reference section 11 (narrative longform, personal essay, exploratory or discovery document, emotionally-driven persuasion, creative writing, in-progress thinking, pedagogical walk-through), surface the mismatch via AskUserQuestion with three options: _Proceed anyway (I understand the pyramid may be the wrong frame) / Switch: route me to the writing skill instead / Cancel_. Honor the choice. If the user proceeds anyway, record `genre_override: true` in intake.md so Phase 5 can prepend a caveat to Audit notes. _Run only the input step matching the mode chosen in step 1; skip the others._ 4. **Mode A (Greenfield) inputs.** Ask for topic, audience, and the reader question (the question you expect the reader to have, which the apex will answer). Use AskUserQuestion or simple prompts as appropriate. 5. **Mode B (Restructure) inputs.** Ask for the draft path (absolute path to a markdown file) OR accept the draft pasted inline. If pasted inline, write it to `{OUTPUT_PATH}/draft.md`. Either way, the construct agent reads `draft.md` from the working directory. 6. **Mode D (Socratic) inputs.** Same as Mode A: ask for topic, audience, and the reader question. The dialogue itself runs in Phase 2, not in intake. Do NOT collect a draft; Mode D builds the pyramid from scratch with the writer. 7. **Write intake.md** with fields: `mode`, `topic_or_draft_path`, `audience`, `reader_question`, `genre`, `domain_limits_acknowledged`, `genre_override`. 8. Mark the Phase 1 task completed. ### Phase 2: Construct Mode-branched. Modes A and B run as one Agent dispatch. Mode D runs as an orchestrator-only turn loop with no Agent dispatch. **Modes A (Greenfield) and B (Restructure):** 1. Read `construct-greenfield-prompt.md` if `mode == greenfield`, or `construct-restructure-prompt.md` if `mode == restructure`. 2. Inject: output path, reference path, empty reviewer feedback (on first dispatch; populated on re-dispatch), `{HANDOFF}` set to `false`, today's date. 3. Dispatch via the host subagent tool. 4. Verify `{OUTPUT_PATH}/construction.md` exists. For Mode B (restructure), also verify `{OUTPUT_PATH}/restructure-notes.md` exists. 5. Mark task completed. On re-dispatch (after a CRITICAL audit gate), inject `audit-summary.md` content as `{REVIEWER_FEEDBACK}` so the construct agent updates `construction.md` in place to address the flagged issues rather than rebuilding from scratch. **Mode D (Socratic):** 1. Read `construct-socratic-prompt.md`. This file is an orchestrator playbook, NOT an Agent dispatch prompt. The orchestrator owns the loop; no Agent is dispatched in Phase 2 for Mode D. 2. Run the turn loop the playbook specifies: each turn is one `AskUserQuestion` plus one inline micro-audit. After each accepted turn, write the partial `{OUTPUT_PATH}/construction.md` in the standard schema with `` placeholders for unanswered nodes; emit a one-line progress summary to the user. 3. Every `AskUserQuestion` carries four standard options: _Other (type my answer)_ (the freeform answer field), _Hand off remaining tiers to Mode A_, _Pause and resume later_, _Cancel_. 4. **Hand-off to Mode A.** If the user picks _Hand off remaining tiers to Mode A_ at any turn: update the state file's `mode` to `greenfield` and add `handoff_from: socratic`; read `construct-greenfield-prompt.md`, set `{HANDOFF}` to `true`, dispatch the greenfield agent. Phase 2 continues from the agent's output; Phases 3-5 run unchanged on the merged pyramid. 5. **Pause.** If the user picks _Pause and resume later_: write the state file with `mode: socratic`, `last_completed_phase: intake`, `last_run_at: `. Emit a one-line confirmation and exit. 6. **Cancel.** Same semantics as Cancel in Modes A and B: working directory artifacts left in place; state file entry removed. 7. **Resume.** Next `/pyramid` invocation in this directory: state file with `mode: socratic` and `last_completed_phase: intake` triggers an `AskUserQuestion`: _"In-flight Socratic dialogue found. Resume from ?"_. On yes, read `construction.md`, count populated nodes vs `` placeholders to infer next turn, re-enter the loop. 8. When all turns complete, verify `{OUTPUT_PATH}/construction.md` exists and contains no `` placeholders. Mark task completed. On re-dispatch (after a CRITICAL audit gate from Phase 3), Mode D's pyramid is treated as the user-built ground truth: re-dispatch goes to `construct-greenfield-prompt.md` with `{HANDOFF}` set to `true` and `{REVIEWER_FEEDBACK}` populated, so the agent updates the construction in place rather than restarting the dialogue. ### Phase 3: Audit panel Four subagent dispatches in parallel when supported. Issue all four host subagent calls in one turn when the platform supports concurrent dispatch. | Prompt file | Output file | Lens | | ------------------------------- | ------------------ | ----------------------------------------------------------------- | | `audits/mece.md` | `audit-mece.md` | Four MECE Audit Questions (reference section 4) | | `audits/so-what.md` | `audit-so-what.md` | So-What / Why-Is-That-True / Caveman Answer (reference section 6) | | `audits/qa-alignment.md` | `audit-qa.md` | Q-A Alignment Audit (reference section 3) | | `audits/inductive-deductive.md` | `audit-logic.md` | Inductive vs Deductive classification (reference section 5) | For each auditor: 1. Read the prompt file from the table above. 2. Inject output path, reference path, empty reviewer feedback. 3. Dispatch via the host subagent tool, all four in the same turn when supported. 4. Verify the corresponding output file exists. 5. Mark the sub-task completed. When all four audits return, consolidate into `audit-summary.md`: ```markdown # Audit Summary ## Verdicts | Auditor | Verdict | Headline | | ------------------- | ------------------------- | ------------------ | | MECE | | | | So-What | ... | ... | | Q-A Alignment | ... | ... | | Inductive/Deductive | ... | ... | ## MECE ## So-What ## Q-A Alignment ## Inductive/Deductive ``` Then check verdicts. **Match on the first whitespace-delimited token of each auditor's `**Verdict:**` line.** Auditors emit `PASS`, `MINOR ISSUES`, or `CRITICAL ISSUES`; only the first token is the gate signal. Expected tokens: `PASS`, `MINOR`, `CRITICAL`. - All four auditors emit `PASS` or `MINOR` → continue to Phase 4 (opener). - One or more auditors emit `CRITICAL` → re-dispatch Phase 2 (construct) with `audit-summary.md` injected as `{REVIEWER_FEEDBACK}`. Re-run Phase 3. Repeat up to 2 total iterations. If still CRITICAL after 2 iterations, present remaining critical issues to the user via AskUserQuestion: _Continue to opener with known logic issues / Pause for manual intervention / Cancel._ Mark phase task completed when the verdict allows progression or the user overrides. ### Phase 4: Opener One Agent dispatch. 1. Read `opener-prompt.md`. 2. Inject: output path, reference path, empty reviewer feedback. 3. Dispatch via the host subagent tool. 4. Verify `{OUTPUT_PATH}/opener.md` exists. 5. Inspect the first non-frontmatter line. If it reads `**Verdict:** MISMATCH`, do NOT treat this as a failure. The opener agent correctly refused to manufacture a bogus complication. Read the `## Reason` and `## Partial opener` sections and ask the user via AskUserQuestion: _Proceed with degraded opener (S and A only, C and Q omitted) / Revise apex by re-running construct with the mismatch note injected as reviewer feedback / Cancel._ 6. If the user chooses to revise the apex, inject the MISMATCH reason into `{REVIEWER_FEEDBACK}` and re-dispatch Phase 2, then re-run Phase 3, then re-run Phase 4. If the user proceeds with the degraded opener, Phase 5 will render only S and A. 7. Mark task completed. The opener is deliberately Phase 4 (not Phase 1) so it is written LAST against a stable apex. This prevents a premature opener from forcing structural changes to the apex, which is the whole point of the pyramid method. ### Phase 5: Render Orchestrator-only. No Agent dispatch. 1. Read `{OUTPUT_PATH}/construction.md` for apex, top-level grouping noun, siblings, and evidence. 2. Read `{OUTPUT_PATH}/opener.md` for the SCQA opener (or the Partial opener if MISMATCH was accepted). 3. Read `{OUTPUT_PATH}/audit-summary.md` for the MINOR flags worth surfacing. 4. Assemble `{OUTPUT_PATH}/pyramid.md` in this shape: ```markdown # **Opener (SCQA).** S: . C: . Q: . A: . ## Apex ## Supporting findings () - - - - - - - - ... ## Audit notes The following MINOR flags did not block the pyramid but are worth knowing: - - - <...> ``` Degraded render cases: - **Opener was MISMATCH and user accepted degraded output.** Replace the SCQA line with a Partial opener rendered from `opener.md`'s `## Partial opener` section (S and A only; omit C and Q). - **All four audits returned PASS.** The Audit notes section reads exactly: _"All four audits passed."_ - **Genre override from domain-limits gate.** Prepend a caveat to Audit notes: _"Genre override: user acknowledged the pyramid may be the wrong frame for this piece."_ Mark task completed and update the state file. ### Step 6: Update state and present Update the state file. The working directory is the _key_ under `projects` (not a field). For that key, write: - `mode`: `greenfield` or `restructure` - `active_reference`: absolute path - `last_completed_phase`: name of the last successful phase - `last_run_at`: ISO timestamp See the State File Format section below for the exact JSON shape. Present `pyramid.md` and `audit-summary.md` to the user. ## Edge Cases - **Working dir does not exist**: create with `mkdir -p`. - **Reference not found at any level**: fall back to the skill default and warn "Using default pyramid reference". - **Phase artifact missing on resume**: re-run that phase. - **Agent dispatch fails**: retry once, then surface the error and pause. - **Auditor returns malformed output** (no `**Verdict:**` line, or an unrecognised token): log, treat as `MINOR`, continue with the remaining auditors. Record the malformed output in `audit-summary.md` under the auditor's section verbatim so the user can inspect it. - **User cancels mid-pipeline**: the state file records the last completed phase; the next invocation resumes from there. - **Audit gate fails twice** (CRITICAL after 2 iterations): present remaining critical issues, ask whether to continue to opener with known issues, pause for manual intervention, or cancel. - **Missing prerequisite artifact on phase jump**: some phases depend on artifacts produced by earlier phases: - `construct` needs `intake.md`. - `audit` needs `construction.md`. - `opener` needs `construction.md` (and benefits from `audit-summary.md` for MINOR flags). - `render` needs `construction.md` AND `opener.md` (and `audit-summary.md` for the notes section). If the user invokes `--phase X` on a directory missing the upstream artifact, ask via AskUserQuestion whether to (a) run the missing upstream phase first, (b) accept a degraded run (only safe for render without opener.md, which renders S-and-A placeholder in place of the SCQA line), or (c) cancel and let the user produce the artifact manually. - **Unknown mode value** (state file contains a value other than `greenfield`, `restructure`, or `socratic`): warn once, fall back to asking the user via AskUserQuestion, and record the corrected value in the state file. - **Mode A (Greenfield) with a draft present in cwd**: if `draft.md` already exists in the working directory but the user picked greenfield, surface the file and ask: _"A draft is present in this directory. Did you mean Restructure mode?"_ via AskUserQuestion. Accept the answer and proceed. - **Mode B (Restructure) with an empty or missing draft**: if `draft.md` is empty (zero bytes) or the provided path does not exist, ask the user to supply the draft or bail to Mode A (Greenfield). - **Mode D (Socratic) repeated block on the same turn**: after two failed attempts on a hard-blocked turn (apex is a label, sibling is a label, sibling count exceeds 5), soften to a warning on the third attempt: _"Letting this through. The audit panel will flag it formally."_ Caps user frustration without abandoning the discipline. - **Mode D with existing `construction.md` from a prior run**: ask via AskUserQuestion _Reset and rebuild via dialogue / Keep existing pyramid (no Mode D needed) / Cancel_. Honor the choice. - **Mode D empty answer in the freeform field**: re-ask the question without consuming a turn. - **Mode D phase-jump invocation (`--phase construct --mode socratic` on a directory without `intake.md`)**: same handling as Mode A; ask whether to run intake first. - **Domain-limits gate override**: the user chose _Proceed anyway_ despite a mismatched genre. The pipeline continues normally. Phase 5 render prepends a caveat to the Audit notes section (see Phase 5 above). ## State File Format `//pyramid-skill-state.json`: ```json { "version": 1, "projects": { "": { "mode": "greenfield", "active_reference": "", "last_completed_phase": "construct", "last_run_at": "2026-04-24T12:00:00Z" } } } ``` Recognised mode values: `greenfield`, `restructure`, `socratic`. Key by absolute working-directory path so multiple in-flight pyramids in the same project each have their own state. After a Mode-D-to-Mode-A hand-off, the `mode` field becomes `greenfield` and an optional `handoff_from: socratic` field is added. ## Phase Identifier Names Used in `--phase` flag and task list: `intake`, `construct`, `audit`, `opener`, `render` ## Behavioral Guidelines - Trigger on memo, recommendation, briefing, decision document, or analytical report intent, and on explicit requests for pyramid or Minto structure. - Do NOT trigger on narrative, personal essay, exploratory or discovery, or pedagogical writing. Route those to the writing skill. - Always announce the active reference in the first response: _"Using pyramid reference: {path}"_. - Always create the task list before dispatching the first phase agent so the user sees what is coming. - Never skip the domain-limits gate silently. Surface it even when the user asked for pyramid explicitly; the writer stays in control but must acknowledge the mismatch. - Auditors emit verdicts (PASS / MINOR / CRITICAL); the orchestrator decides whether to gate or proceed based on those tokens. - The opener is written LAST (Phase 4), against a stable apex, so it cannot force structural changes to the apex. A MISMATCH verdict is a legitimate outcome, not a failure: it means the apex cannot support a clean SCQA and the user must decide whether to degrade the opener or revise the apex.