Ipa Author Guide

ipa-author-guide

Write IPA documentation guides that conform to the Guide Format Standard. Each guide follows a fixed 9-section template (Title, Overview, When to Use, Before You Start, Before/Target State, Steps, Verification, Troubleshooting, Next Steps) and is populated by researching the codebase — skill files, CloudFormation templates, and .env configuration.

Guides live at docs/docs/guides/ and render automatically via Docusaurus autogenerated sidebars.

User Input

$ARGUMENTS

Expected: a topic, goal, or workflow name — e.g., local development setup, deploying the backend, path to production. If the topic is missing or ambiguous, ask the user.

Pre-Execution Checks

1. Read the Guide Format Standard to load the section specifications and writing conventions:

   docs/docs/developer-docs/docs/guide-format-standard.md
   

   Keep this in context throughout — it governs every section.

2. Read the documentation structure reference for site conventions (front matter, file naming, landing pages):

   docs/docs/developer-docs/docs/documentation-structure.md
   

3. Check if a guide already exists for this topic:

   docs/docs/guides/
   

   • If a matching file exists → switch to update mode. Read the existing guide and ask the user what to change.
   • If no match → proceed with create mode.

4. Scan the guides index page (docs/docs/guides/index.md) to understand what guides already exist and avoid overlap.

Phase 1: Gather Requirements

Collect the following from the user, one question at a time. Skip questions the user has already answered in their initial request. Ask follow-up questions when an answer is ambiguous or incomplete — do not guess.

5. Goal — "What single goal does this guide accomplish? What will the reader have done when they finish?"

   This becomes the Title and Overview. The goal must be a single, concrete outcome — not a topic or concept. If the user describes multiple goals, recommend splitting into separate guides and confirm which one to write first.

6. Trigger conditions — "When should a builder reach for this guide? What situation or need triggers it?"

   This becomes the When to Use This Guide section. Collect 2–4 bullet points describing the conditions. Also ask: "Are there situations where this guide should NOT be used? What should the builder do instead?"

7. Prerequisites — "What must be true before the reader starts? What tools, access, .env variables, or prior guides are required?"

   This becomes Before You Start. Collect only IPA-specific prerequisites — assume competence with standard development tooling (AWS CLI, git, etc.).

8. Before/after state — "What exists before the guide begins, and what will exist after?"

   This becomes Before / Target State. For infrastructure guides, describe the AWS resources and stack state before and after. Prompt for specifics: "What stacks are deployed before? What stacks, endpoints, or resources exist after?"

9. Workflow steps — "Walk me through the steps at a high level. What does the reader do, in order?"

   This becomes the Steps section. Collect the sequence of actions. For each step, ask:

   • What command or action does the reader perform?
   • What is the expected result?
   • Are there decision points or optional steps?

   If the workflow has more than 10 major steps, recommend splitting into linked sub-guides and confirm scope.

10. Verification — "How does the reader confirm that the guide achieved its goal? What command or check proves the end state was reached?"

    This becomes the Verification section. Every guide must have verification — do not skip this question.

11. Known failure modes — "Are there common problems a reader might encounter? If so, what is the likely cause and fix for each?"

    This becomes the Troubleshooting section (conditional). If the user has no known failure modes, the section is omitted entirely — do not generate speculative entries.

12. Next steps — "What should the reader do after finishing this guide? What related guides, reference docs, or follow-on tasks are relevant?"

    This becomes the Next Steps section. For guides that deploy infrastructure, always include a link to /ipa-destroy and teardown documentation.

13. Present a summary of the gathered requirements and confirm before proceeding:

    "Here is what I will write. Does this match your intent, or would you like to change anything?"

Phase 2: Research the Codebase

ultrathink — Shallow research produces guides with incorrect commands, missing parameters, or wrong expected outputs. Trace every step through the actual codebase artifacts.

14. Based on the gathered requirements, identify the codebase artifacts relevant to this guide. Read each one to extract accurate commands, parameters, outputs, and configuration:

    Artifact Type	Location	What to Extract
    Skill files	.claude/skills/ipa-*/SKILL.md	Invocation syntax, workflow phases, parameters, expected behavior
    CloudFormation templates	infra/cfn/*/	Resource types, parameters, outputs, stack names
    Stack skills	.claude/skills/ipa.stack.*/SKILL.md	Stack parameters, wiring, deploy/teardown order
    Environment config	.env.example or .env references in skills	Required variables, naming conventions
    Generated Makefiles	scripts/*.mk	Make targets, target names, 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

15. For each step in the workflow, verify:

    • The command is accurate (matches the skill file or Makefile target)
    • The expected output is realistic (matches what the tool actually produces)
    • Required .env variables are listed in Before You Start
    • Referenced stacks and resources match the CloudFormation templates

16. Cross-reference existing guides to avoid duplicating content. Link to existing guides rather than repeating their steps.

Phase 3: Draft the Guide

17. Create the guide file at docs/docs/guides/{guide-name}.md where {guide-name} is a lowercase, hyphenated slug derived from the title.

18. Write the front matter:

    ---
    title: {Guide Title}
    sidebar_position: {N}
    ---
    

    Determine sidebar_position by checking existing guides in docs/docs/guides/ and placing the new guide in a logical position.

19. Write each section in the exact order defined by the Guide Format Standard. Do not add, remove, rename, reorder, or merge sections.

    Section Drafting Rules

    Title (H1):

    • Short, action-oriented — e.g., "Local Development Setup", "Path to Production"
    • Do not use the "How to [verb] [outcome]" pattern
    • Do not use vague titles ("Getting Started") or compound goals ("Deploy and Monitor the Backend")

    Overview:

    • One to two sentences answering: "What will I have done when I finish this guide?"
    • No conceptual background, architecture explanations, or motivation

    When to Use This Guide:

    • Two to four bullet points with decision criteria
    • Include "Do not use this guide if..." when applicable
    • Do not restate the overview

    Before You Start:

    • Bullet list of IPA-specific prerequisites only
    • Include: .env variables, prior guides, required access
    • Do not include general tooling setup (installing AWS CLI, configuring git)

    Before / Target State:

    • Concise "you have X → you will have Y" description
    • Use a before/after table for infrastructure guides
    • Do not repeat the overview or list steps

    Steps:

    • Numbered, imperative steps (H3 headings: ### 1. Step summary)
    • Each step follows the pattern: context sentence → command in fenced code block → expected result
    • Imperative verbs: "Run", "Open", "Configure" — not "You should run"
    • Goal before action: "To deploy the stack, run:" — not "Run this to deploy:"
    • Location before action when relevant: "In the project root directory, run:"
    • Prefix optional steps with "Optional:"
    • Sub-steps (a, b, c) sparingly — no deeper than one level
    • Fewer than 10 major steps — split if more

    Verification:

    • Commands and expected output confirming the end state
    • Required in every guide — never skip
    • Include the most critical check; link to comprehensive testing if needed

    Troubleshooting (conditional):

    • Include only when known failure modes exist from Phase 1, question 11
    • Problem → likely cause → fix format (table or definition list)
    • Three to five entries maximum
    • Do not generate speculative entries — omit the section entirely if no known issues exist

    Next Steps:

    • Three to five bullet links: related guides, reference docs, teardown
    • Do not summarize what was accomplished
    • For infrastructure guides, include /ipa-destroy link

Phase 4: Apply Writing Conventions

20. Review the draft against the cross-cutting writing conventions from the Guide Format Standard:

    Procedural language:

    • Second person ("you") in procedural sections
    • Imperative mood for actions — "Run", "Open", "Add"
    • No "please", no "you should", no "let us"
    • No directional language ("above", "below", "the following")
    • Active voice and short sentences

    Tone:

    • Formal throughout — no contractions ("do not" not "don't", "it is" not "it's")
    • Third person acceptable in non-procedural sections (Overview, When to Use)
    • No filler phrases ("In order to", "It should be noted that")

    Technical content:

    • Fenced code blocks for all commands, config, file paths, and output — no screenshots
    • No hardcoded tool versions — reference "latest" or link to release pages
    • No internal AWS account IDs — use 123456789012 placeholder
    • Define jargon on first use or link to Key Terms glossary

    Admonitions (Docusaurus syntax — use sparingly, max 2 per Steps section):

    • :::note — supplementary, non-essential information
    • :::warning — must-know to avoid failure or destructive action
    • :::tip — optional optimization or shortcut

Phase 5: Validate

ultrathink — Shallow validation means the guide ships with structural violations, incorrect commands, or missing sections that undermine reader trust and the consistency of the guide set.

21. Structural validation — confirm the guide has every required section in the correct order:

    #	Section	Status	Check
    1	Title (H1)	Required	Present, short, action-oriented
    2	Overview (H2)	Required	1–2 sentences, no background
    3	When to Use This Guide (H2)	Required	2–4 bullet decision criteria
    4	Before You Start (H2)	Required	Bullet list, IPA-specific only
    5	Before / Target State (H2)	Required	Before/after framing
    6	Steps (H2)	Required	Numbered, imperative, fewer than 10
    7	Verification (H2)	Required	Commands + expected output
    8	Troubleshooting (H2)	Conditional	Present only if known failure modes exist
    9	Next Steps (H2)	Required	3–5 links

22. Content accuracy — for each command in the Steps and Verification sections:

    • Confirm the command matches a real skill invocation, Makefile target, or CLI command from the codebase
    • Confirm expected output is realistic based on what the tool produces
    • Confirm referenced .env variables are listed in Before You Start
    • Confirm referenced stacks and resources match CloudFormation templates

23. Writing convention compliance:

    • No contractions anywhere in the guide
    • No "please", "you should", "let us", or filler phrases
    • All commands in fenced code blocks
    • No hardcoded account IDs (use 123456789012)
    • Admonitions: no more than 2 in the Steps section
    • No sections added, removed, renamed, or reordered beyond the template

24. Cross-reference check:

    • Every guide referenced in Before You Start and Next Steps either exists or is clearly marked as planned
    • No duplicate content with existing guides — link instead of repeat

25. If validation fails on any check, fix the issue and re-validate. Do not present the guide to the user until all checks pass.

Rules

Structural

• The 9-section template is fixed. Do not add, remove, rename, reorder, or merge sections.
• Troubleshooting is the only conditional section — include it only when known failure modes were collected in Phase 1.
• Each guide addresses one goal. If the goal is compound, split into linked guides.
• Fewer than 10 major steps. Longer workflows become linked sub-guides, each with their own Verification.

Content

• Every command, parameter, and expected output must be verified against the codebase. Do not fabricate commands or outputs.
• When information is missing and cannot be derived from the codebase, ask the user. Do not guess.
• Do not include conceptual background in the Overview — link to explanation documents instead.
• Do not include general tooling prerequisites in Before You Start — only IPA-specific items.
• Do not generate speculative Troubleshooting entries — only include issues with known causes and fixes.

Style

• Follow the Guide Format Standard writing conventions exactly. The conventions are not suggestions — they are requirements.
• Formal tone, no contractions, imperative mood, goal-before-action, location-before-action.
• Fenced code blocks for everything technical. No screenshots.
• Admonitions sparingly — max 2 in Steps.

File Conventions

• File name: lowercase, hyphenated slug — e.g., local-development.md, path-to-production.md
• Location: docs/docs/guides/{guide-name}.md
• Front matter: title (required), sidebar_position (set based on existing guides)
• No _category_.json creation unless explicitly needed for ordering

Completion Report

Created/Updated:

• Guide: docs/docs/guides/{guide-name}.md

Guide Summary:

• Title: {title}
• Goal: {one-sentence goal}
• Steps: {count}
• Verification: {brief description of what is verified}
• Troubleshooting: {included / omitted}
• Codebase artifacts referenced: {list of skill files, templates, stacks read}

Next steps:

• Preview locally: cd docs && npm start → navigate to the guide at http://localhost:3001/guides/{guide-name}
• Review against the Guide Format Standard checklist
• If this guide deploys infrastructure, verify the commands against a real environment