Docs Workflow Planning

Documentation Planning Step

Step skill for the docs-orchestrator pipeline. Follows the step skill contract: parse args → dispatch agent → write output.

Arguments

• $1 — JIRA ticket ID (required)
• --base-path — Base output path (e.g., .agent_workspace/proj-123)

Input

/requirements/requirements.md

Output

/planning/plan.md

Execution

1. Parse arguments

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

Set the paths:

INPUT_FILE="${BASE_PATH}/requirements/requirements.md"
OUTPUT_DIR="${BASE_PATH}/planning"
OUTPUT_FILE="${OUTPUT_DIR}/plan.md"
mkdir -p "$OUTPUT_DIR"

2. Dispatch agent

You MUST use the Agent tool to invoke the docs-planner subagent. Do NOT read the agent's markdown file or attempt to perform the agent's work yourself — the agent has a specialized system prompt and must run as an isolated subagent.

Agent tool parameters:

• subagent_type: docs-planner
• description: Create documentation plan for

Prompt (pass this as the prompt parameter to the Agent tool):

> Create a comprehensive documentation plan based on the requirements analysis. > > Read the requirements from: ` > > The plan must include: > 1. Gap analysis (existing vs needed documentation) > 2. Module specifications (type, title, audience, content points, prerequisites, dependencies) > 3. Implementation order based on dependencies > 4. Assembly structure (how modules group together) > 5. Content sources from JIRA and PR/MR analysis > > Save the complete plan to: `

[Include only if /scope-req-audit/evidence-status.json exists] Append the following paragraph to the prompt:

> Code evidence status is available at /scope-req-audit/evidence-status.json. Read it and use the evidence status when making scoping decisions: > > - Grounded requirements: create full module specifications as normal. Use the key_files for each grounded requirement as content source references in the module spec — these are the actual source files where the feature is implemented. The code-evidence step will use them for targeted retrieval > - Partial requirements: create module specifications but note what evidence was found and what is missing — flag for SME review. Include available key_files as partial source references > - Absent requirements: do NOT create module specifications. Instead, list them in a "Deferred requirements (no code evidence)" section at the end of the plan, including the recommended action from the evidence status. These may be unimplemented features — documenting them risks fabrication > > If discovered_repos lists repos that weren't indexed, note them in the deferred section as potential sources for resolving absent requirements.

3. Verify output

After the agent completes, verify the output file exists at ``.

If no output file is found, report an error.

4. Write step-result.json

Read `` and count the number of module specifications. Count each occurrence of:

• Level-3 headings (###) whose text begins with Module:
• Numbered or bulleted list items within the "Module Specifications" section that start with Module:

Ignore headings or list items outside the "Module Specifications" section, and skip items inside code blocks or blockquotes. Treat duplicate module titles as separate modules (no deduplication). This count becomes the module_count field.

Write the sidecar to /step-result.json:

{
  "schema_version": 1,
  "step": "planning",
  "ticket": "",
  "completed_at": "",
  "module_count": 
}

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
• Source: 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.