teamcraft-jcg:capture-requirements

What this skill does

## Goal

Facilitate a live requirements session between a BA and their client. Confirm understanding through visualizations the client can see and react to — because reviewing a mockup together is far more effective than agreeing on words. Each visualization the client approves becomes concrete requirements in a structured PRD. The client decides what gets visualized and when — propose visuals, don't generate them unasked, because a visualization the client didn't request doesn't confirm anything.

Output is a structured PRD — new or updated — that downstream agents can act on without ambiguity.

## Hard Constraints

- The PRD describes WHAT and WHY. Never HOW. Technology choices belong in a separate tech decisions session. Redirect if raised.
- HTML mockups must be fully self-contained. Never use anchor tags with `href` for navigation — Cowork's preview pane treats them as external navigation and leaves the session. Use JavaScript click handlers for all interactivity (scrolling, section toggling, tab switching).
- Confluence strips `<script>` tags from page content, so interactive HTML mockups cannot be embedded directly in Confluence pages. Instead, upload them as attachments and link to them from the PRD (see "Upload Companion Artifacts" below).

## Understand the PRD Standard First

Before any client interaction, read `references/example-prd.md`. This is the complete standard for the PRD you will produce. Understand every section — you need to know what the final document requires so you can gather information for all of them during the session.

## Establish Intent

Understand what the user is here for before starting anything else. Are they starting a brand new project? Continuing a previous session? Do they already have material — requirements docs, sketches, spreadsheets, notes from stakeholder meetings? The material could be anywhere: in Confluence, on their local machine, typed from memory, an uploaded image, or a combination of sources.

If they have existing material, ask how they want to provide it. If they point to Confluence, load the page with `mcp__sooperset-mcp-atlassian__confluence_get_page`. If they need to find something, use `mcp__sooperset-mcp-atlassian__confluence_search`. If they provide material another way, work with what they give you.

If `$ARGUMENTS` contains a Confluence page URL or page ID, that's an existing PRD — load it and summarize its current state so the client has context.

## Capture Requirements Visually

As the client describes what they want, propose creating interactive visualizations to confirm understanding — UI mockups, workflow diagrams, navigation structures, data models, user journey maps, or whatever fits the concept being discussed. Explain briefly why: it's far easier to confirm requirements when you can see and interact with them together. If the `frontend-design` skill is available, use it for generating higher-fidelity mockups.

Visualizations should be interactive where appropriate: clickable navigation, working form elements, expandable sections, hover states, tab switching. Every confirmed visual maps to concrete requirements with acceptance criteria in the PRD. Iterate until the client confirms each visualization before moving on.

Surface gaps proactively — areas the client hasn't mentioned that a complete product would need. Ask, don't assume.

## Produce the PRD

Produce the PRD following the standard you read at the start. Attempt to include every section unless the user directs otherwise. Include a companion artifacts section that lists every approved visualization by name — someone reading the PRD should know what supporting materials were produced and confirmed during the session.

For follow-up sessions: integrate new requirements into the existing PRD. Summarize what changed — new sections, modified requirements, removed scope — before finalizing.

## Review and Store

Show the complete PRD for review. Do not store until the user confirms.

Confluence is the default storage location. Ask which Confluence space to use. Use `mcp__sooperset-mcp-atlassian__confluence_search` to surface available spaces if the user doesn't know the space key. Once the space is confirmed, use `mcp__sooperset-mcp-atlassian__confluence_get_page_children` to browse its structure and recommend a parent page location based on what already exists. Confirm the location before creating with `mcp__sooperset-mcp-atlassian__confluence_create_page`. For follow-up sessions, update the existing page with `mcp__sooperset-mcp-atlassian__confluence_update_page`. If the user wants to store it somewhere else, do that instead.

## Upload Companion Artifacts

After the PRD page is created or updated, upload all approved visualizations as attachments to the same page using `mcp__sooperset-mcp-atlassian__confluence_upload_attachment`. This keeps the PRD and its supporting materials together.

**How to attach and reference each artifact type:**

- **Diagrams and images (PNG, SVG):** Upload the file, then embed it inline in the PRD using markdown image syntax: `![Diagram Name](filename.png)`. Confluence automatically resolves the filename to the attached image — the image renders directly on the page.

- **Interactive HTML mockups:** Confluence strips `<script>` tags, so HTML files cannot render inline. Upload the HTML file as an attachment, then add a download link in the PRD's companion artifacts section using this URL pattern: `[Download Mockup Name](https://{site}.atlassian.net/wiki/download/attachments/{pageId}/{filename})`. The reader clicks the link, downloads the file, and opens it in their browser to interact with it.

The PRD's companion artifacts section should list every uploaded artifact by name with its link, so someone reading the PRD knows exactly what supporting materials exist and can access them directly from the page.

## Done

Share the Confluence page URL and page ID. Summarize what was captured, list the companion artifacts uploaded to the page, and note any open questions that need follow-up.