Documentation Writing Step

Step skill for the docs-orchestrator pipeline. Follows the step skill contract: run script → dispatch agent → verify output.

Execution

1. Run the script

Run the build script to parse arguments, validate inputs, determine mode, and create output directories:

bash ${CLAUDE_SKILL_DIR}/scripts/build_writing_args.sh <args>

Pass through the args unquoted so each flag and value is a separate shell word. Do NOT wrap the entire args string in quotes — the script uses positional argument parsing and each --flag value pair must be a separate argument. The script emits JSON on stdout:

{
  "mode":                "update-in-place | draft | fix",
  "ticket":              "PROJ-123",
  "format":              "adoc | mkdocs",
  "input_file":          "<base-path>/planning/plan.md",
  "code_analysis_dir":   "<base-path>/code-analysis/ | null",
  "has_code_analysis":   true | false,
  "pr_analysis_dir":     "<base-path>/pr-analysis/ | null",
  "has_pr_analysis":     true | false,
  "output_dir":          "<base-path>/writing",
  "output_file":         "<base-path>/writing/_index.md",
  "docs_repo_path":      "<path> | null",
  "source_repo_path":    "<path> | null",
  "additional_repo_paths": ["<path>", ...],
  "additional_code_analysis_dirs": ["<path>", ...],
  "fix_from":            "<path> | null",
  "verify_output":       true | false
}

If the script exits non-zero, stop and report the error from stderr.

2. Dispatch the docs-writer agent

You MUST use the Agent tool to invoke the docs-writer 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.

Select the prompt based on mode and format from the JSON output. See agent prompts for the full prompt text for each combination.

Agent tool parameters for all modes:

• subagent_type: docs-skills:docs-writer
• description: use the value from the Description column
• run_in_background: false (the orchestrator must wait for the writer to finish before verifying output)

In every prompt, substitute the <TICKET>, <INPUT_FILE>, <OUTPUT_FILE>, <OUTPUT_DIR>, <DOCS_REPO_PATH>, <FIX_FROM>, <CODE_ANALYSIS_DIR>, <PR_ANALYSIS_DIR>, <SOURCE_REPO>, <ADDITIONAL_REPO_PATHS>, <ADDITIONAL_CODE_ANALYSIS_DIRS>, HAS_CODE_ANALYSIS, and HAS_PR_ANALYSIS placeholders with the corresponding values from the script's JSON.

3. Verify output

If verify_output is true in the script's JSON output, check that output_file exists.

If verify_output is false (fix mode), no verification is needed — files are edited in place.

4. Write step-result.json

Skip this step if mode is "fix" (fixes edit files in place — no new manifest to parse).

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, passing mode and format from the build script's JSON output:

python3 ${CLAUDE_SKILL_DIR}/scripts/write_step_result.py \
  --ticket "<TICKET>" \
  --manifest "<OUTPUT_FILE>" \
  --mode "<mode from script JSON>" \
  --format "<format from script JSON>" \
  --sidecar "<OUTPUT_DIR>/step-result.json"

The script parses absolute file paths from the manifest's table rows and 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.