Workflow Planning & Writing Skills

Create, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs, extracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design decision, or updating the status of an existing ADR. Does not create or update enforceable coding standards or conventions — use coding-standard for that. Does not write feature or system documentation — use project-documentation instead.

Sharpens and stress-tests an existing plan file through multiple codebase-grounded review passes, editing it in place and recording every finding and iteration in cross-referenced companion files. Use this skill whenever the user wants to iterate on, refine, tighten, or improve a plan — including terse commands like "iterate", "refine it", or "iterate for correctness" where a plan is present in context. Also use it when the user asks to verify, validate, or confirm feasibility of an approach (e.g., "can you verify this will work", "check this for correctness", "is this sound") — the defining signal is that the user wants critical evaluation of a proposed approach, not execution of it. Produces two companion files in an artifacts/ subfolder next to the plan: review-findings.md (every finding raised and how it was resolved) and review-iteration-history.md (round-by-round record of specialists engaged and plan changes applied). Do NOT use for implementing plan steps, generating new plans from scratch, writing test plans, code review, or bug investigation.

Builds a feature specification from scratch through a relentless, evidence-based interview that walks the design tree decision-by-decision, resolving dependencies as it goes. Use when the user wants to plan, design, scope, specify, or flesh out a new feature, capability, or system behavior before implementation — including requests like "help me plan X", "spec out this feature", "design the Y flow", or "let's figure out what it should do". Explores the codebase, project documentation, coding standards, and ADRs to resolve questions before asking the user, and always offers a recommended answer when questions must be surfaced. Produces a feature-specification.md focused on system behaviors, coordinations, processes, and user interactions — not implementation detail. Does not refine or stress-test an existing plan — use iterative-plan-review. Does not investigate bugs or failures — use investigate. Does not analyze existing architecture — use architectural-analysis. Does not document already-built features — use project-documentation. Does not record architectural decisions — use architectural-decision-record.

Splits a body of context into a sequence of vertical-slice build phases where each phase is independently demonstrable to a real user and each builds on the work of the previous. Use when the user wants to plan, sequence, phase, slice, break down, or order the build of a feature, capability, system, or initiative — including requests like "split this into phases", "what should we build first", "create a build plan", "phase this work", "turn this into vertical slices", "outline the order of delivery", or "what's our roadmap". Accepts any source of context — gap analyses, PRDs, design documents, feature specifications, conversation notes, ADRs, requirements lists, or inline descriptions — and produces a plain-language build-phase-outline.md indexed by stable phase IDs. Each phase explains what gets built, why it lands at that position, the outcome a real person can be shown end-to-end, cross-references back to the source artifact for traceability, and preconditions. Foundational or prerequisite phases appear first only when dependencies require them; feature work otherwise sequences for earliest demoable value. The information-architect reviews the rendered document so the result is findable, scannable, and builds comprehension progressively. Does not produce implementation detail — use plan-implementation. Does not specify behavior that has not yet been decided — use plan-a-feature. Does not perform gap analysis between two artifacts — use gap-analysis. Does not record architectural decisions — use architectural-decision-record. Does not refine an existing plan — use iterative-plan-review.

Creates and maintains project documentation for features, systems, and components. Discovers project structure dynamically to work across any technology stack. Use when documenting how a feature, system, or component works — including writing, updating, or organizing docs. Does not scan or detect the project's technology stack — use project-discovery for repository analysis and config detection. Does not create architectural decision records — use architectural-decision-record for ADRs. Does not create or update coding standards — use coding-standard instead. Does not generate PR descriptions — use update-pr-description for that.

Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI. Use when writing, drafting, or updating pull request descriptions, PR summaries, or PR bodies. Requires the gh CLI to be installed and a PR to already exist for the current branch. Does not review code or post review comments — use code-review for local review or gh-pr-review for posting a review to GitHub.