# Docs Workflow Requirements

> Analyze documentation requirements for a JIRA ticket using a two-pass fanout. Pass 1 dispatches a discovery agent to enumerate requirements. Pass 2 fans out one deep-analysis agent per requirement for isolated, thorough analysis. Assembles the standard requirements.md output. Invoked by the orchestrator.

- **Type:** Skill
- **Install:** `agentstack add skill-abhatt-rh-redhat-docs-agent-tools-docs-workflow-requirements`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abhatt-rh](https://agentstack.voostack.com/s/abhatt-rh)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** https://github.com/abhatt-rh/redhat-docs-agent-tools/tree/main/plugins/docs-tools/skills/docs-workflow-requirements
- **Website:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

## Install

```sh
agentstack add skill-abhatt-rh-redhat-docs-agent-tools-docs-workflow-requirements
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Requirements Analysis Step

Step skill for the docs-orchestrator pipeline. Follows the step skill contract: **parse args → discover → fan out → merge → write output**.

This skill uses a two-pass architecture to analyze documentation requirements:

1. **Discovery pass** — A single `requirements-discoverer` agent enumerates requirements from JIRA, PRs, and specs, producing a JSON skeleton
2. **Deep analysis pass** — One `requirements-analyst` agent per requirement, all running in parallel, each performing thorough analysis with a clean context window
3. **Merge** — The orchestrator assembles per-requirement JSON results into the standard `requirements.md` format

## Arguments

- `$1` — JIRA ticket ID (required)
- `--base-path ` — Base output path (e.g., `.agent_workspace/proj-123`)
- `--pr ` — PR/MR URL to include in analysis (repeatable)

## Output

```
/requirements/requirements.md
/requirements/step-result.json
```

## Execution

### 1. Parse arguments

Extract the ticket ID, `--base-path`, and any `--pr` URLs from the args string.

Set the output path:

```bash
OUTPUT_DIR="${BASE_PATH}/requirements"
OUTPUT_FILE="${OUTPUT_DIR}/requirements.md"
DISCOVERY_FILE="${OUTPUT_DIR}/discovery.json"
mkdir -p "$OUTPUT_DIR"
```

### 2. Pass 1 — Discovery

Dispatch one `requirements-discoverer` agent to enumerate requirements from all sources.

```
Agent:
  subagent_type: requirements-discoverer
  description: "Discover requirements for "
  prompt: |
    Discover documentation requirements for JIRA ticket .

    PR/MR URLs to include in analysis (merge with any auto-discovered, dedup):
    - 
    - 

    Save your JSON output to: 

    Follow your standard discovery procedure: JIRA fetch, ticket graph traversal,
    PR listing, spec identification, requirement enumeration.
```

The PR URL bullet list is conditional — include those bullets only if `--pr` URLs were provided.

After the agent completes, read ``.

If the discovery JSON has an `error` field set, STOP and report the error (likely an access failure).

### 3. Parse discovery output

Read the discovery JSON and extract:
- `requirements` — the list of requirement skeletons
- `related_tickets` — shared context for all deep-analysis agents
- `release` — release/sprint identifier
- `ticket_summary` — primary ticket summary
- `sources_consulted` — all sources the discovery agent found

If `requirements` is empty, write a minimal `requirements.md` noting that no requirements were found, write `step-result.json`, and exit successfully.

### 4. Pass 2 — Fan out deep analysis

For each requirement in the discovery skeleton, dispatch one `requirements-analyst` agent. Launch ALL agents in a **single message** (parallel execution).

For each requirement, use:

```
Agent:
  subagent_type: requirements-analyst
  description: "Analyze REQ-NNN: "
  prompt: |
    Perform deep analysis of this single documentation requirement.

    REQUIREMENT:
    

    RELATED_TICKETS:
    

    RELEASE: 

    [If --repo was provided: "REPO_PATH: "]

    Fetch detailed content from each source, perform web search expansion,
    and produce complete documentation requirements with acceptance criteria.

    Print your JSON result to stdout.
```

The `REPO_PATH` line is conditional — include it only if `--repo` was passed to this step. When present, the analyst verifies the requirement against the codebase, identifies existing docs, and extracts code references.

**Important:** All Agent calls MUST be in a single message so they run in parallel.

### 5. Merge results

Each agent returns a JSON object (or text containing a JSON object). Parse each agent's response to extract the JSON.

If an agent's response is not valid JSON or is missing the `id` field, create a fallback entry. Carry forward the skeleton's source references so the requirement retains traceability even on failure:

```json
{
  "id": "",
  "title": "",
  "error": "Agent did not return valid JSON",
  "priority": "",
  "category": "",
  "sources": [
    {"label": "", "url": "", "note": "From discovery (deep analysis failed)"}
  ],
  "summary": "",
  "user_impact": null,
  "scope": null,
  "documentation_actions": [],
  "acceptance_criteria": [],
  "references": [],
  "web_findings": [],
  "is_breaking_change": false,
  "deprecation_version": null,
  "notes": "Deep analysis failed — using skeleton data only"
}
```

Convert each entry in the skeleton's `sources` array to the analyst format: use `key` (for JIRA) or the URL as the label, preserve the URL, and add a note indicating discovery-only data.

Collect all per-requirement results into a list ordered by requirement ID.

### 6. Assemble requirements.md

Write `` by assembling the merged results into the standard requirements format. The document structure must match the existing output contract exactly:

```markdown
# Documentation Requirements

**Source**: 
**Date**: 
**Release/Sprint**: 

## Summary

- Total requirements analyzed: 
- New modules needed: 
- Existing modules to update: 
- Breaking changes requiring docs: 

## Requirements by priority

### Critical

#### REQ-001: [title]
- **Source**: [label](url) | [label](url)
- **Summary**: [summary]
- **User impact**: [user_impact]
- **Documentation action**:
  - [ ] [action] `[file]` ([type]) [note if present]
- **Acceptance criteria**:
  - [ ] [criterion]
- **References**:
  - [label](url): [note]

### High
[Same format, requirements with priority "high"]

### Medium
[Same format, requirements with priority "medium"]

### Low
[Same format, requirements with priority "low"]

## Documentation scope

### New documentation needed

| Requirement | Scope | References |
|-------------|-------|------------|
| REQ-XXX | [From documentation_actions where action is "Create"] | [source labels] |

### Existing documentation to update

| Requirement | What changed | References |
|-------------|-------------|------------|
| REQ-XXX | [From documentation_actions where action is "Update"] | [source labels] |

## Breaking changes

[Table of requirements where is_breaking_change is true. Omit section if none.]

| Change | Migration steps needed | Deprecation notice | References |
|--------|------------------------|-------------------|------------|

## Notes

[Aggregate any non-null notes from requirements. Omit section if none.]

## Related tickets

[Format related_tickets from discovery output. Omit section if empty.]

## Sources consulted

### JIRA tickets
[From sources_consulted.jira_tickets — deduplicated across all requirements]

### Pull requests / Merge requests
[From sources_consulted.pull_requests — deduplicated]

### Code files
[From references with type "code" across all requirements — deduplicated]

### Existing documentation
[From sources_consulted.existing_docs — deduplicated]

### External references
[From references without type "code" that are not JIRA/PR/web_findings — deduplicated]

### Web search findings
[From web_findings across all requirements — deduplicated by URL]
```

**Priority section rules:**
- Only include priority sections that have requirements (omit empty `### High` if no high-priority requirements)
- Requirements with errors should be included under their original priority with a note: `**Note:** Deep analysis failed for this requirement. Skeleton data only.`

**Deduplication:** Sources consulted and references are gathered across all per-requirement results. Deduplicate by URL or file path.

### 7. Write step-result.json

Run the title-extraction script:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/parse_title.py ""
```

The script prints `{"title": "..."}` to stdout. If it exits non-zero, report the stderr message as an error.

Use the `title` value from the script's JSON output to write the sidecar to `/step-result.json`:

```json
{
  "schema_version": 1,
  "step": "requirements",
  "ticket": "",
  "completed_at": "",
  "title": ""
}
```

### 8. Verify output

Verify that `` and `/step-result.json` exist.

## Notes

- **Two-pass architecture:** Pass 1 (discovery) is lightweight — JIRA traversal, PR listing, spec identification. Pass 2 (deep analysis) is thorough — each requirement gets a dedicated agent with a clean context window
- **Context isolation:** Each deep-analysis agent sees only one requirement's sources. This prevents context degradation when analyzing tickets with 10+ requirements
- **Parallel execution:** All pass-2 agents are dispatched in a single message for parallel execution
- **Error isolation:** A failed deep-analysis agent does not block other requirements — the merge step uses skeleton data as a fallback
- **Output contract:** The assembled `requirements.md` is identical in format to the previous single-pass output. Downstream consumers (scope-req-audit, planning, orchestrator) see no change
- **Discovery JSON:** The `discovery.json` file is retained in the output directory as a debugging artifact. It is not consumed by downstream steps
- **Intermediate artifacts:** The previous version had the requirements-analyst save intermediary files to `artifacts/`. The deep-analysis agents do not write intermediary files — their structured JSON output is the artifact. If intermediary research is needed for audit, it can be reconstructed from the discovery JSON and per-requirement sources

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** [abhatt-rh/redhat-docs-agent-tools](https://github.com/abhatt-rh/redhat-docs-agent-tools)
- **License:** Apache-2.0
- **Homepage:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-abhatt-rh-redhat-docs-agent-tools-docs-workflow-requirements
- Seller: https://agentstack.voostack.com/s/abhatt-rh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.