/ipa.author.guide
Write IPA documentation guides conforming to the Guide Format Standard. Each guide follows a fixed 9-section template and is populated by researching the codebase.
Invocation
/ipa.author.guide
Optionally pass a topic, goal, or workflow name:
/ipa.author.guide local development setup
/ipa.author.guide deploying the backend
/ipa.author.guide path to production
Parameters
/ipa.author.guide gathers all parameters interactively. An optional topic argument seeds the conversation.
| Input | Description |
|---|---|
| Topic | A topic, goal, or workflow name (e.g., local development setup). If omitted, the skill asks. |
| Goal | Single concrete outcome the guide accomplishes |
| Trigger conditions | 2-4 bullet points describing when a builder should reach for this guide |
| Prerequisites | Tools, access, .env variables, or prior guides required before starting |
| Before/after state | What exists before the guide and what will exist after |
| Workflow steps | Ordered sequence of actions the reader performs |
| Verification | Commands or checks that prove the end state was reached |
| Known failure modes | Common problems with likely causes and fixes (optional — omit if none) |
| Next steps | Related guides, reference docs, or follow-on tasks |
What It Does
The skill executes five phases after pre-execution checks:
Pre-Execution Checks
Reads the Guide Format Standard and Documentation Structure to load section specifications and site conventions. Checks docs/docs/guides/ for an existing guide on the topic — if found, switches to update mode.
Phase 1 — Gather Requirements
Collects the goal, trigger conditions, prerequisites, before/after state, workflow steps, verification, known failure modes, and next steps through interactive prompts — one question at a time. Presents a summary for confirmation before proceeding.
Phase 2 — Research the Codebase
Reads codebase artifacts to extract accurate commands, parameters, outputs, and configuration for each guide step:
| Artifact Type | Location | What Is Extracted |
|---|---|---|
| Skill files | .claude/skills/ipa.*/SKILL.md | Invocation syntax, workflow phases, parameters |
| CloudFormation templates | infra/cfn/*/ | Resource types, parameters, outputs, stack names |
| Pattern definitions | .claude/skills/ipa.compose/patterns/*/PATTERN.md | Stack sequence, wiring, deploy/teardown order |
| Environment config | .env references in skills | Required variables, naming conventions |
| Generated Makefiles | scripts/*.mk | Make targets, execution order |
| Security disposition | .claude/skills/ipa.*/SECURITY.md | IAM permissions, known deferrals |
| Troubleshoot files | .claude/skills/ipa.*/TROUBLESHOOT.md | Known failure modes, causes, fixes |
Phase 3 — Draft the Guide
Creates the guide file at docs/docs/guides/{guide-name}.md with the 9-section template:
| # | Section | Status |
|---|---|---|
| 1 | Title (H1) | Required |
| 2 | Overview | Required |
| 3 | When to Use This Guide | Required |
| 4 | Before You Start | Required |
| 5 | Before / Target State | Required |
| 6 | Steps | Required |
| 7 | Verification | Required |
| 8 | Troubleshooting | Conditional — only when known failure modes exist |
| 9 | Next Steps | Required |
Phase 4 — Apply Writing Conventions
Reviews the draft against the Guide Format Standard writing conventions: formal tone, no contractions, imperative mood, goal-before-action ordering, fenced code blocks for all technical content, and no more than 2 admonitions per Steps section.
Phase 5 — Validate
Runs four validation passes:
| Check | What It Verifies |
|---|---|
| Structural validation | All required sections present in correct order |
| Content accuracy | Commands match real skill invocations, Makefile targets, or CLI commands |
| Writing convention compliance | No contractions, no filler phrases, all commands in code blocks |
| Cross-reference check | Linked guides exist, no duplicate content with other guides |
Outputs
| Artifact | Path | Description |
|---|---|---|
| Guide | docs/docs/guides/{guide-name}.md | Documentation guide conforming to the 9-section template |
The guide renders automatically via Docusaurus autogenerated sidebars — no manual sidebar configuration is needed.
Examples
Write a guide for a specific topic:
/ipa.author.guide local development setup
The skill asks clarifying questions about the goal, prerequisites, steps, and verification, then researches the codebase and drafts the guide.
Write a guide from a stub:
/ipa.author.guide @docs/docs/guides/extending-with-skills.md
Pass an existing stub file as context. The skill reads the embedded guidance notes, asks any remaining questions, and replaces the stub with a complete guide.
Update an existing guide:
/ipa.author.guide composing a solution
If a guide already exists for the topic, the skill switches to update mode and asks what to change.
Related Skills
- /ipa.author.stack — Creates the stack skills and patterns that guides often document
- /ipa.compose — Frequently referenced in guides as part of the IPA workflow
- /ipa.deploy — Frequently referenced in guides for deployment steps