Menu
Use when creating or updating a functional spec for a user flow listed in column B of the User-Flows-Details Sheet
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when authoring or updating developer-facing design specs under docs/design for one or more canonical functional specs (many-to-many via tags), especially architecture decisions, technical tradeoffs, states, data flows, schemas, source-file references, and gaps between flow behavior and current design coverage
Use when creating or updating end-user help pages, user documentation, screen docs, feature help pages, or docs under `docs/user-guide/`. Trigger on "author user guide", "create user guide", "new user guide", "update user guide", "document <screen>", "help page for <feature>", or "/authoring-user-guide".
Use when the user wants to write or improve a prompt for Claude, ChatGPT, Gemini, Cursor, Claude Code, GitHub Copilot, Windsurf, Bolt, v0, Midjourney, DALL-E, Stable Diffusion, or another AI-powered tool.
Use when writing or tightening prose for functional specs, design documents, user guides, or implementation plans, especially when draft text is wordy, vague, passive, duplicative, or hard to scan. Do not use for AI prompt-writing, code comments, commit messages, general chat, or unrelated prose.
| name | authoring-functional-spec |
| description | Use when creating or updating a functional spec for a user flow listed in column B of the User-Flows-Details Sheet |
| version | 0.3.0 |
Author the source-of-truth functional spec for one canonical User-Flows-Details Sheet row. One canonical user flow maps to exactly one functional spec — refuse to create a second spec for a canonical ID that already has one. Design docs are downstream; do not conflate them with the functional spec. The spec must live in the repo identified by Sheet column C. Code grounding comes from that repo; read code from other repos only when the user explicitly identifies them as supporting context.
This skill is not for design specs, implementation plans, end-user help pages, or AI prompt-writing requests. For implementation-plan requests, hand the user the canonical ID and spec path — what happens next is the user's decision.
Create a task for each item. Mark each task in_progress when starting the phase and completed as soon as it finishes — before moving to the next:
gws exists and gws auth status exits zero; otherwise abort with
Run gws auth login first, then retry.git remote get-url origin.references/using-gws.md. Case-fold and trim names; never use a hardcoded repo allowlist. Abort with an error listing the Sheet-derived repo names if the current repo is not in the allowed list.superpowers:verification-before-completion is reachable. If it is not available, substitute a manual re-read of all required frontmatter and section fields at Phase 7.Use the canonical ID present in the user's message if one is given. Otherwise ask which canonical ID to author. If the author cannot name it, use references/using-gws.md to list candidate IDs for the current repo, filtered by the runtime-resolved Sheet repo list.
Fetch the row for the column B canonical ID. Extract B canonical ID, C repo, D category, E title, H status, and K persona. Do not write to the Sheet. If no exact row matches, abort and ask the user to add or correct the Sheet row.
If column H status is Retired, abort:
This flow is marked Retired in the User-Flows-Details Sheet. No spec will be authored or updated for a retired flow. If this retirement is wrong, ask a Sheet owner to update column H first.
Compare the current repo to Sheet column C. Abort with an error if they do not match. The target path is docs/functional/<canonical-id>/README.md. If the target exists, update it in place — do not create a sibling, alternate, or duplicate spec. If it does not exist, create it.
Child pages may exist alongside the README (docs/functional/<canonical-id>/<page>.md) as author-managed supporting material — design context, UI detail, reference sketches that would lower the altitude of the main spec. This skill authors and reviews README.md only.
Set shape and persona using the enums in references/spec-template.md. Read references/shape-lenses.md for the matching section menu. Apply discipline from references/brainstorming.md.
After resolving all gaps, write the behavioral summary (format in references/brainstorming.md) and prompt: "Behavioral model agreed. Here's what I'll draft — let me know if anything needs adjusting before I write the spec." Wait for user approval before proceeding to Phase 6.
references/spec-template.md and references/altitude-discipline.md; use doc-skills:writing-clearly-and-concisely if availableid, title, shape, persona; add renamed-from / absorbs only when applicableGoal, Inputs, Outputs, Invariants, Cross-refs when applicable; choose remaining sections from the shape menu; omit what doesn't applyreferences/reviewing.md.doc-skills:writing-clearly-and-concisely to tighten prose.references/altitude-discipline.md.superpowers:verification-before-completion before claiming completion.<path>. Let me know if you want any changes — I'll commit once you're happy."After approval:
git commit -m "docs(functional): author functional spec for <canonical-id>"git commit -m "docs(functional): update functional spec for <canonical-id>"Never run git push. Summarize canonical ID, target path, sections populated, and remaining Open Questions.
references/spec-template.md — frontmatter schema and expected section list.references/using-gws.md — read-only gws commands, including column-C repo resolution.references/brainstorming.md — brainstorm rules, spec clarity, hard gate, behavioral summary format.references/reviewing.md — review tiers and self-review checklist.references/altitude-discipline.md — altitude rule and cite boundaries.references/shape-lenses.md — shape menus.