Docs Workflow Scope Req Audit

Scope Requirements Audit Step

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

This skill classifies each JIRA requirement from the requirements step as grounded, partial, or absent by dispatching one subagent per requirement. Each subagent receives learn-code analysis context (module registry, summaries, onboarding guide) and can inspect the actual source code with Read/Grep/Glob. The planning step then uses these classifications to scope documentation modules — grounded requirements get full specs, partial ones are flagged for SME review, and absent ones are deferred to prevent documenting unimplemented features.

Arguments

• $1 — JIRA ticket ID (required)
• --base-path — Base output path (e.g., .agent_workspace/proj-123)
• --repo — Path to the source code repository (required, provided by orchestrator)

Input

/requirements/requirements.md
/

Output

/scope-req-audit/evidence-status.json
/scope-req-audit/summary.md
/scope-req-audit/step-result.json

Execution

1. Parse arguments and validate inputs

Extract the ticket ID, --base-path, and --repo from the args string.

Set the paths:

REQUIREMENTS_FILE="${BASE_PATH}/requirements/requirements.md"
OUTPUT_DIR="${BASE_PATH}/scope-req-audit"
EVIDENCE_STATUS_FILE="${OUTPUT_DIR}/evidence-status.json"
SUMMARY_FILE="${OUTPUT_DIR}/summary.md"
mkdir -p "$OUTPUT_DIR"

Validate:

• Verify --repo was provided. If not, STOP with error: "scope-req-audit requires --repo. The orchestrator should provide the repo path."
• Verify $REQUIREMENTS_FILE exists. If not, STOP with error: "Requirements step must complete before scope-req-audit."
• Verify the repo path exists and is a directory. If not, STOP with error: "Repo path does not exist: ``."

2. Discover related repos

Scan the source repo's top-level markdown files for GitHub and GitLab repository URLs that are not the current repo. This provides context for recommended actions when requirements are absent.

Files to scan:

• README.md, README.rst, README
• CONTRIBUTING.md
• docs/*.md (one level only)

For each file, extract URLs matching:

• https://github.com// (GitHub)
• https://gitlab./ (GitLab)

Filter out:

• The current repo URL (discover the remote with git -C "$REPO_PATH" remote -v — which reads the repo without changing the shell's working directory — and use the first available remote's URL). Normalize before comparing: strip trailing .git, convert git@:/ SSH URLs to https://// form
• Duplicate URLs (after normalization)
• URLs that are clearly not repos (e.g., GitHub issue links, badge URLs)

Store the results as a list of discovered_repos entries, each with:

• url — the repository URL
• source — the file and approximate location where it was found (e.g., README.md)
• relevance — a brief note on why it might be relevant (e.g., "Python SDK referenced in project README")

3. Parse requirements

Read $REQUIREMENTS_FILE and extract each requirement. The requirements-analyst produces requirements in this pattern:

### REQ-NNN: [title]

**Summary**: [description]

For each requirement, extract:

• id — the REQ-NNN identifier
• title — the requirement title
• summary — the summary text

If no requirements are found matching this pattern, STOP with error: "No requirements found in requirements.md. Expected REQ-NNN pattern."

4. Pre-flight: resolve and load learn-code analysis data

Resolve and load the structured code analysis produced by learn-code. This data provides module-level understanding of the codebase that classifiers use alongside direct source inspection.

4a. Resolve analysis location

Derive the repo name and check for existing analysis:

REPO_NAME="$(basename "$REPO_PATH")"
# Derive the docs-repo root from BASE_PATH (/.agent_workspace/)
# by stripping from `.agent_workspace` onward. Do NOT use `git rev-parse`, which
# returns whichever repo the cwd is inside and points at the wrong root if the
# agent drifted into the source repo.
GIT_ROOT="${BASE_PATH%%/.agent_workspace/*}"
ANALYSIS_PATH="${GIT_ROOT}/.agent_workspace/${REPO_NAME}"

Check for existing analysis at ${ANALYSIS_PATH}/synthesis/ONBOARDING.md.

If it does not exist:

Check if ${ANALYSIS_PATH}/workflow/ contains a progress file with status: "in_progress".

• If a progress file exists with in-progress status: report that a learn-code analysis is incomplete and offer to resume it.
• If no progress file exists or analysis directory does not exist: run learn-code:

Skill: learn-code, args: "${REPO_PATH}"

Wait for it to complete. If it fails, STOP with error including the failure details.

After learn-code completes (or if analysis already existed), verify ${ANALYSIS_PATH}/synthesis/ONBOARDING.md exists. If not, STOP with error: "learn-code analysis failed to produce ONBOARDING.md at ${ANALYSIS_PATH}/synthesis/ONBOARDING.md."

4b. Verify analysis files and record paths

Verify that the expected analysis files exist at ${ANALYSIS_PATH}/. Do not read their contents into context — agents read them directly from disk.

Check these files:

| File | Required | |------|----------| | detection/detection.json | Yes | | module-registry/registry.json | Yes | | module-analysis/summary.json | Yes | | relationships/relationships.json | No (may not exist for small repos) | | synthesis/ONBOARDING.md | Yes (verified in 4a) |

For each missing required file (other than ONBOARDING.md, already verified in 4a), log a warning but continue — agents handle missing data gracefully. For missing optional files, log a note.

Write the discovered repos list from step 2 to a shared file so agents can read it from disk instead of receiving it inline:

# Write to disk — agents read from DISCOVERED_REPOS_FILE
cat > "${OUTPUT_DIR}/discovered-repos.json" 
JSONEOF

Record ANALYSIS_PATH for use in agent prompts. Do not read or assemble any analysis file contents.

5. Fan out: dispatch one agent per requirement

For each requirement extracted in step 3, dispatch one Agent call. Launch ALL requirement agents in a single message (parallel execution).

Each agent reads analysis data from disk and writes its result to /evidence-.json. Where `` is the zero-padded requirement number extracted from the REQ-NNN id (e.g., REQ-001 produces evidence-001.json).

See [agent prompts](references/agent-prompts.md#fan-out-classifier-prompt) for the full classifier prompt template.

Important: All Agent calls MUST be in a single message so they run in parallel. Do not dispatch them sequentially.

6. Collect results from disk

After all agents complete, verify that the expected per-requirement JSON files were written to disk.

EXPECTED_COUNT=
ACTUAL_COUNT=$(ls ${OUTPUT_DIR}/evidence-*.json 2>/dev/null | wc -l)
echo "Evidence files: ${ACTUAL_COUNT}/${EXPECTED_COUNT}"

HARD GATE — do NOT proceed to step 7 (merge) until ACTUAL_COUNT equals EXPECTED_COUNT. If any agents are still running, wait for them to complete. After all agents have returned, if files are still missing:

1. Identify which REQ IDs have no corresponding evidence-.json
2. Log: "Missing evidence files for: REQ-003, REQ-007" (list actual missing IDs)
3. The merge agent (step 7) will create fallback entries for missing files — proceed to step 7 only after confirming the missing IDs

7. Assemble output via merge agent

Delegate the assembly of evidence-status.json and summary.md to a merge subagent. This keeps the full classification data (~20-50KB) out of the orchestrator's context.

See [agent prompts](references/agent-prompts.md#merge-agent-prompt) for the full merge agent prompt template.

8. Verify merge output

Verify that $EVIDENCE_STATUS_FILE and $SUMMARY_FILE were written by the merge agent:

test -f "$EVIDENCE_STATUS_FILE" && test -f "$SUMMARY_FILE" && echo "OK" || echo "MISSING"

If either file is missing, treat it as a step failure.

The sidecar script in step 10 reads evidence-status.json directly, so no inline extraction is needed.

9. Extract secondary repo references

After writing evidence-status.json, run the secondary repo extraction script to identify repos referenced in gap classification actions:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-workflow-scope-req-audit/scripts/extract_secondary_repos.py \
  --evidence-status "$EVIDENCE_STATUS_FILE" \
  --primary-repo "$REPO_PATH" \
  --fetch-pr-paths \
  --max-repos 3

The script parses recommended_action fields from partial/absent requirements, extracts GitHub/GitLab repo URLs, groups requirements by target repo, and optionally fetches PR file paths to derive suggested_scope directories.

Read the JSON array output and merge it into evidence-status.json as a secondary_repos field:

{
  "secondary_repos": [
    {
      "url": "https://github.com/org/companion-repo",
      "source": "gap_classification",
      "requirements": ["REQ-002", "REQ-004"],
      "pr_refs": ["#262", "#317"],
      "priority": "secondary",
      "suggested_scope": ["pkg/controller/", "pkg/mutator/"]
    }
  ]
}

If the script returns an empty array, set secondary_repos: [] in evidence-status.json. The field must always be present so downstream consumers (orchestrator, planning) can check it without guarding against missing keys.

Also update summary.md to include a "Secondary Repos (from gap analysis)" section if any were found:

## Secondary Repos (from gap analysis)

- [https://github.com/org/companion-repo](https://github.com/org/companion-repo) — REQ-002, REQ-004 (3 PRs, scope: pkg/controller/, pkg/mutator/)

10. Write step-result.json

Do not hand-author the sidecar — a hand-written sidecar drifts from the schema and uses an orchestrator-delayed timestamp instead of a real wall-clock one. Run the script:

python3 ${CLAUDE_SKILL_DIR}/scripts/write_step_result.py \
  --ticket "" \
  --evidence-status "$EVIDENCE_STATUS_FILE" \
  --sidecar "${OUTPUT_DIR}/step-result.json"

The script reads evidence-status.json to extract recommendation, summary counts, discoveredrepos length, and secondaryrepos length. It writes the conformant step-result.json with a real wall-clock completed_at. If the script exits non-zero, fix the arguments and re-run; do not substitute a stub.

11. Verify output

Verify that $EVIDENCE_STATUS_FILE, $SUMMARY_FILE, and ${OUTPUT_DIR}/step-result.json exist.

How downstream steps use the output

The planning step checks for /scope-req-audit/evidence-status.json. If it exists, the planner uses evidence status when scoping modules:

• Grounded requirements get full module specifications
• Partial requirements get module specifications with a gap note flagging SME review
• Absent requirements are listed in a "Deferred requirements (no code evidence)" section — no module specs are created for them

If evidence-status.json does not exist (step was skipped or not configured), the planning step works exactly as before — all requirements are included. This preserves composability.

Notes

• Fanout pattern: Each requirement is classified by an independent subagent with a clean context window. This prevents context degradation when processing many requirements — classification quality for REQ-015 is identical to REQ-001
• Disk-based data flow: Agents write their JSON classifications to per-requirement files (evidence-NNN.json) on disk instead of returning them to the orchestrator context. The merge agent reads from disk to assemble evidence-status.json and summary.md. This prevents 15+ agent results and ~300KB of analysis context from accumulating in the orchestrator's context window
• Compact prompts: Agent prompts reference ANALYSIS_PATH by path instead of embedding the full analysis JSON. Each agent reads analysis files directly from disk. This reduces per-agent prompt size from ~200KB to ~0.3KB
• Learn-code analysis: Analysis data is produced by learn-code and cached at .agent_workspace//. If analysis already exists from a prior run, it is reused. The first workflow run for a repo pays the analysis cost; subsequent runs skip it. Analysis files are referenced by path in agent prompts — never read into the orchestrator context
• Source inspection: Subagents inspect actual source files using Read/Grep/Glob. The learn-code analysis provides a structural map (modules, APIs, relationships) that guides where to look, but the final classification is based on direct evidence in the source code
• Parallel execution: All subagent Agent calls are dispatched in a single message for parallel execution. The orchestrator waits for all to complete before merging
• Error isolation: A failed subagent does not affect other requirements — the merge agent creates a fallback entry with "status": "absent" and an "error" field for diagnostics
• This step queries the primary source repo only. The secondary_repos output enables the orchestrator to clone and index companion repos if needed
• discovered_repos (step 2) surfaces repos found in README/docs. secondary_repos (step 9) surfaces repos referenced in gap classification actions — these are more targeted because they're tied to specific absent/partial requirements

Source & license

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

• Author: opendatahub-io
• Source: opendatahub-io/docs-skills
• License: Apache-2.0

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