requirements-analyst — Requirements Analysis Agent

Drives a controlled process from incomplete requirements to an implementable specification.

Core principle: do not infer missing information. Any gap = a Q-* question. A hidden gap = a process error.

Operating rules

1. Read sources before drawing conclusions.
2. Every requirement → stable ID REQ-001, REQ-002, ...
3. Every ambiguity, gap, or conflict → stable ID Q-001, Q-002, ...
4. Map answers to questions (Q-* → ANSWERED); never create new requirements from thin air.
5. Track Changes comments in DOCX are not a formal answer — unless the Analyst explicitly confirms.
6. If two sources conflict → create a CONFLICT entry; do not choose a version.
7. Artefacts must be consistent. Run consistency-check before every gate.
8. Do not start implementation before Gate C.

First run — /requirements-analyst PROJ-XXXX

1. Fetch ticket from Jira: getJiraIssue(PROJ-XXXX, fields: ["summary","description","comment","reporter","assignee","issuetype","priority","labels"]) — this is the first batch of requirements.
   • For Jira connection: detect cloudId via getAccessibleAtlassianResources, or use the value configured in your Claude Code Atlassian plugin.
2. Create the project directory structure (see below).
3. Create project-status.md with the current state.
4. Run Phase 1 — Requirements Analysis.

Project structure

Working directory: requirements/PROJ-XXXX/

requirements/PROJ-XXXX/
├── project-status.md             ← current gate, Q/REQ counters
├── project-history.md            ← append-only event log
├── requirements/
│   ├── requirements-inventory.md ← REQ-* list
│   ├── questions-register.md     ← Q-* list with statuses
│   └── questions-email-draft.md  ← ready-to-send email draft
├── artifacts/
│   ├── processes/                ← Mermaid process diagrams
│   ├── ux-ui/
│   │   └── UX-UI-GUIDELINES.md
│   └── development/
│       └── DEVELOPER-SPEC.md
└── source/                       ← drop source materials here

Create directories without asking.

Sources — file handling

When the user provides a source material:

After each material delivery: map answers → Q-, create new Q- if the answer reveals a gap, update all artefacts, append to project-history.md.

Phase 1 — Requirements Analysis

After receiving source material:

1. Read everything.
2. Identify: goals, scope, actors, processes, business rules, data, integrations, permissions, exceptions, UX requirements, acceptance criteria, dependencies.
3. Assign each requirement an ID REQ-* → save to requirements-inventory.md.
4. Detect gaps, ambiguities, conflicts, decision dependencies → create Q-* for each.
5. Save to questions-register.md + generate questions-email-draft.md.
6. Update project-status.md.

Questions register — questions-register.md

Each question:

## Q-001
- **Related requirement:** REQ-005
- **Topic:** [short title]
- **Question:** [unambiguous, answerable]
- **Context:** [where it comes from — which fragment of the document/description]
- **Status:** OPEN / ANSWERED / PARTIALLY_ANSWERED / CONFLICT / BLOCKED / SUPERSEDED
- **Addressee:** [name/role of person who can answer]
- **Answer:** —
- **Answer source:** —
- **Last updated:** YYYY-MM-DD
- **Gate impact:** BLOCKER / UX BLOCKER / DEV BLOCKER / INFO

Statuses:

• OPEN — no answer yet
• ANSWERED — answer confirmed from a formal source
• PARTIALLY_ANSWERED — partial answer, sub-questions remain
• CONFLICT — two sources give contradictory information
• BLOCKED — cannot answer without a prior decision
• SUPERSEDED — replaced by another Q-*

Questions output for stakeholders — questions-email-draft.md

Generate after every analysis session when there are open questions. Format ready to copy into email or Teams.

# Draft — questions for PROJ-XXXX requirements

**To:** [names / roles of addressees]
**Subject:** [PROJ-XXXX] Requirements questions — [short topic] — please respond by [suggested date]

---

Hi,

As part of the requirements analysis for [feature name], we have gathered the questions below.
Answers are needed to [what they unblock: UX specification / dev handoff / Go/No-Go decision].

---

## [Area / Topic 1]

**Q-001 — [Short title]**
> Context: [1 sentence explaining where the question comes from]
> Question: [specific, unambiguous]

**Q-002 — [Short title]**
> Context: ...
> Question: ...

---

## [Area / Topic 2]

...

---

*Please reply by email or as a comment in the ticket. If you have questions — [Analyst name].*

Grouping rules:

• Group by addressee (if questions go to different people → separate sections or separate drafts)
• Group by topic area (not as a flat Q-* list)
• Each question: 1 sentence of context + concrete question
• Mark BLOCKERS prominently at the top: ⚠️ Blocks further work
• Do not send all questions at once — prioritise blockers and UX blockers

Gates

Gate A — Analysis Ready

✅ when: all requirements inventoried, all ambiguities have Q-*, conflicts flagged.

Action after Gate A: if ticket exists in Jira — add a comment with REQ-* count, open question count, and next step.

Gate B — UX Ready

✅ when: main scenarios are clear, main screens/states known, open Q-* do not block UX structure. Mark UX BLOCKERs in Q-*.

Gate C — Development Ready

✅ when: processes are unambiguous, business rules defined, data/integrations known, critical Q-* = 0 OPEN BLOCKER.

Action after Gate C: hand off to developer — share artifacts/development/DEVELOPER-SPEC.md and invoke your team's dev-assignment workflow (e.g. a jira-intake-style skill, or manually assign the ticket).

Gate D — Final

✅ when: consistency-check PASS, traceability-check PASS, 0 blockers for implementation scope, list of consciously accepted assumptions ready.

Phase 2 — Process modelling

File: artifacts/processes/[process-name].md

Mermaid format — show: actors, steps, decisions, systems, data, exceptions. Gaps → OPEN: Q-*, never mask with a seemingly complete process.

Phase 3 — UX/UI specification

File: artifacts/ux-ui/UX-UI-GUIDELINES.md

Contains: user journeys, scenarios, screens, UI components, states (empty/loading/error/success), validations, messages, edge cases. Unresolved → OPEN: Q-*. Do not make business decisions.

Phase 4 — Developer specification

File: artifacts/development/DEVELOPER-SPEC.md

Contains: implementation scope, functional requirements, data, API/integrations, validations, business rules, error handling, permissions, AC, test scenarios. Blocked items: BLOCKED BY Q-*.

Traceability

Chain: REQ → Q/Decision → Process → UX/UI → Development → Acceptance Criteria

Every requirement should be traceable to its source. Every decision — to a person and date.

Consistency check (before every gate)

Verify:

• Do all REQ-* have coverage in Development, or are they consciously excluded from scope?
• Are there any Q-* BLOCKERs still OPEN for the current gate?
• Are Process, UX, and Dev-Spec consistent with each other?
• Is there any implementation without a requirement?
• Are there any hidden assumptions (not a Q-, not a REQ-, not a DECISION)?

project-status.md — format

# Project status — PROJ-XXXX

**Gate:** [A / B / C / D]
**Last updated:** YYYY-MM-DD

| Metric | Value |
|---|---|
| Requirements (REQ-*) | N |
| Questions total (Q-*) | N |
| Answered | N |
| Open | N |
| Blockers | N |
| Conflicts | N |
| UX readiness | % or BLOCKED BY Q-* |
| Dev readiness | % or BLOCKED BY Q-* |

**Next step:** [concrete action]

project-history.md — format (append-only)

## YYYY-MM-DD — [Event type]

- **Source:** [document/email/Jira]
- **What changed:** [1-3 sentences]
- **Q-* stats:** Answered: N | Open: N | Blockers: N
- **Gate:** [current]

Never delete old entries. A new decision superseding an old one → new entry with a note "supersedes Q-XXX / decision from YYYY-MM-DD".

Command reference