From 3558d4c658a6716ee12189ac9f3cc52566227da1 Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Thu, 26 Mar 2026 17:11:23 +0000 Subject: [PATCH 01/10] Add doc set generation from scratch via docset workflow Extend the docs-orchestrator to support generating entire MkDocs documentation sets from multiple input sources (JIRA tickets via JQL, local files, and Google Drive artifacts). Changes: - Generalize orchestrator $1 from "JIRA ticket ID" to "workflow ID" - Add --jql, --tickets, --inputs (repeatable), --no-jtbd flags - Make JIRA pre-flight conditional (only when JIRA access is needed) - Extend requirements-analyst agent with multi-source input handling - Add docs-docset-scaffold skill for MkDocs project scaffolding - Add docs-docset-workflow.yaml (7-step docset workflow definition) - Bump docs-tools version to 0.0.16 Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/.claude-plugin/plugin.json | 2 +- .../docs-tools/agents/requirements-analyst.md | 57 +++++- .../skills/docs-docset-scaffold/SKILL.md | 170 ++++++++++++++++++ .../skills/docs-orchestrator/SKILL.md | 61 ++++--- .../defaults/docs-docset-workflow.yaml | 43 +++++ .../defaults/docs-workflow.yaml | 2 +- .../hooks/workflow-completion-check.sh | 4 +- .../docs-workflow-requirements/SKILL.md | 43 ++++- 8 files changed, 345 insertions(+), 37 deletions(-) create mode 100644 plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md create mode 100644 plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml diff --git a/plugins/docs-tools/.claude-plugin/plugin.json b/plugins/docs-tools/.claude-plugin/plugin.json index 8201d0b7..911c8f7a 100644 --- a/plugins/docs-tools/.claude-plugin/plugin.json +++ b/plugins/docs-tools/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docs-tools", - "version": "0.0.15", + "version": "0.0.16", "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.", "author": { "name": "Red Hat Documentation Team", diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index e5702ffe..966b16fa 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -30,6 +30,49 @@ Proceeding with incorrect or assumed information leads to: **It is ALWAYS better to stop and wait for correct access than to produce incorrect documentation.** +## Parse arguments + +- `$1` — Workflow ID. Treated as a JIRA ticket ID by default (fetched via jira-reader). **Exception**: if any of `--jql`, `--tickets`, or `--inputs` flags are provided, `$1` is treated as a plain workflow identifier (not fetched as a JIRA ticket). Use only the flags for actual source input. +- `--base-path ` — Base output directory for all step outputs +- `--pr ` — PR/MR URLs (repeatable) +- `--jql ` — JQL query for bulk JIRA ticket fetch (uses `jira_reader.py --jql --fetch-details`) +- `--tickets ` — Comma-separated list of JIRA ticket IDs (fetches each via `jira_reader.py --issue`) +- `--inputs ` — Additional input sources (repeatable). Each value is auto-detected by type: + +| Pattern | Type | Processing | +|---|---|---| +| `docs.google.com/document/...` | Google Doc | Convert via `gdoc2md.py` | +| `docs.google.com/presentation/...` | Google Slides | Convert via `gdoc2md.py` | +| `docs.google.com/spreadsheets/...` | Google Sheets | Convert via `gdoc2md.py` | +| `https://...` or `http://...` (non-Google) | Web article | Extract via `article_extractor.py` | +| Everything else | Local file path | Read via Read tool | + +### Processing --inputs values + +**Google Drive URLs:** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-convert-gdoc-md/scripts/gdoc2md.py "" +``` + +**Web URLs (non-Google):** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "" --format markdown +``` + +**Local files:** Read directly using the Read tool. + +### Multi-source mode + +When `--jql`, `--tickets`, or `--inputs` are provided, gather ALL sources before analysis: + +1. Fetch all JIRA tickets from `--jql` (with `--fetch-details`) and `--tickets` +2. Run `--graph` on each fetched ticket to discover linked Google Docs and PRs +3. Process each `--inputs` value based on auto-detected type +4. Process each `--pr` URL +5. Merge all gathered content, then proceed with the standard analysis methodology below + +All sources are combined into a single unified `requirements.md` in the same format as single-ticket mode. + ## When invoked 1. Gather source materials: @@ -428,12 +471,22 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/redhat-docs-toc/scripts/toc_extractor.py -- ### Extracting article content with article-extractor -Download and extract content from Red Hat documentation pages: +Download and extract content from web pages: + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." --format markdown +``` + +### Converting Google Drive documents with docs-convert-gdoc-md + +Convert Google Docs, Slides, and Sheets to Markdown/CSV: ```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." +python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-convert-gdoc-md/scripts/gdoc2md.py "" ``` +Supports Google Docs (→ Markdown), Slides (→ Markdown), and Sheets (→ CSV). Requires `gcloud auth login --enable-gdrive-access`. + ## Key principles 1. **User focus**: Prioritize requirements that affect user experience diff --git a/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md b/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md new file mode 100644 index 00000000..16242f31 --- /dev/null +++ b/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md @@ -0,0 +1,170 @@ +--- +name: docs-docset-scaffold +description: >- + Creates an MkDocs project from scratch based on a documentation plan. Reads + plan.md to extract categories and parent topics, then generates mkdocs.yml, + directory structure, and category landing pages. Use this skill when + scaffolding a new documentation set as part of the docset workflow. +argument-hint: --base-path --format mkdocs [--draft] +allowed-tools: Read, Write, Bash, Glob +--- + +# Doc Set Scaffold Step + +Step skill for the docs-orchestrator pipeline. Follows the step skill contract: **parse args → scaffold project → write manifest**. + +## Arguments + +- `$1` — Workflow ID (required) +- `--base-path ` — Base output path (e.g., `.claude/docs/my-product-guide`) +- `--format mkdocs` — Output format (only `mkdocs` supported for now) +- `--draft` — If set, scaffold into `/scaffold/` staging area. Otherwise, scaffold into the repo working directory. + +## Output + +``` +/scaffold/scaffold-info.md +``` + +## Execution + +### 1. Parse arguments + +Extract the workflow ID, `--base-path`, `--format`, and `--draft` flag from the args string. + +### 2. Read the plan + +Read the documentation plan from `/planning/plan.md`. + +Extract: +- **Categories**: Top-level JTBD categories (e.g., "Get started", "Configure", "Troubleshoot") +- **Parent topics**: Within each category, the parent topic titles +- **Module list**: Individual modules with their types (CONCEPT, PROCEDURE, REFERENCE) and titles +- **Project name**: From the plan's `**Project**` field or the workflow ID + +If the plan does not use JTBD categories (e.g., `--no-jtbd` was used upstream), extract the top-level organizational groupings and parent topics as they appear in the plan. + +### 3. Determine output location + +- **Draft mode** (`--draft`): Scaffold into `/scaffold/site/` +- **Non-draft mode**: Scaffold into the repo working directory (current directory) + +### 4. Create MkDocs project structure + +Generate the following files and directories: + +#### `mkdocs.yml` + +```yaml +site_name: +theme: + name: material + features: + - navigation.sections + - navigation.expand + - navigation.indexes + - search.suggest + - content.code.copy + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - tables + - attr_list + - toc: + permalink: true + +nav: + - Home: index.md + - : + - /index.md + - : /.md + - : /.md + - : + - /index.md + - ... +``` + +Populate the `nav` section from the plan's categories and parent topics. Use kebab-case for directory and file names derived from titles. + +#### `docs/index.md` + +```markdown +--- +title: +description: +--- + +# + +<2-3 sentence overview derived from the plan's summary or JTBD statement> +``` + +#### Category directories and index pages + +For each category, create: +- `docs//` directory +- `docs//index.md` with: + +```markdown +--- +title: +description: +--- + +# + +<1-2 sentence overview of what this category covers> +``` + +#### Placeholder module files + +For each parent topic listed in the plan, create a placeholder file at the expected path so that the nav references resolve. These are minimal files that the docs-writer will overwrite with full content: + +```markdown +--- +title: +description: +--- + +# + + +``` + +### 5. Write scaffold manifest + +Write a manifest to `/scaffold/scaffold-info.md`: + +```markdown +# Scaffold Manifest + +**Workflow ID**: +**Format**: mkdocs +**Output location**: +**Date**: + +## Files created + +- `mkdocs.yml` — MkDocs configuration with nav structure +- `docs/index.md` — Landing page +- `docs//index.md` — Category landing pages (one per category) +- `docs//.md` — Placeholder module files (one per parent topic) + +## Navigation structure + + + +## Categories + +| Category | Directory | Topics | +|---|---|---| +| | `docs//` | N topics | +``` + +### 6. Verify output + +Verify that `mkdocs.yml` and `docs/index.md` exist at the output location. diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 13088a27..1f2b2671 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-orchestrator description: Documentation workflow orchestrator. Reads the step list from .claude/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine. -argument-hint: [--workflow ] [--pr ]... [--mkdocs] [--draft] [--create-jira ] +argument-hint: [--workflow ] [--pr ]... [--inputs ]... [--jql ] [--tickets ] [--mkdocs] [--draft] [--no-jtbd] [--create-jira ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, AskUserQuestion, WebSearch, WebFetch --- @@ -22,7 +22,10 @@ if [[ -z "${JIRA_AUTH_TOKEN:-}" ]]; then fi ``` -1. If `JIRA_AUTH_TOKEN` is still unset → **STOP** and ask the user to set it in `~/.env` +1. **JIRA token check** — require `JIRA_AUTH_TOKEN` only when JIRA access is needed: + - If `--jql` or `--tickets` flags are passed → **STOP** if unset (JIRA is explicitly requested) + - If the workflow is the default `docs-workflow` → **STOP** if unset (default workflow requires JIRA) + - Otherwise (custom workflow without JIRA flags) → skip the check 2. Warn (don't stop) if `GITHUB_TOKEN` or `GITLAB_TOKEN` are unset 3. Install hooks (safe to re-run): @@ -32,11 +35,15 @@ bash scripts/setup-hooks.sh ## Parse arguments -- `$1` — JIRA ticket ID (required). If missing, STOP and ask the user. +- `$1` — Workflow ID (required). For the default `docs-workflow`, this is a JIRA ticket ID. For custom workflows (e.g., `--workflow docset`), this can be any identifier such as a doc set name. If missing, STOP and ask the user. - `--workflow ` — Use `.claude/docs-.yaml` instead of `docs-workflow.yaml` - `--pr ` — PR/MR URLs (repeatable, accumulated into a list) +- `--inputs ` — Additional input sources (repeatable, accumulated into a list). Each value can be a local file path, Google Drive URL, or web URL. Forwarded to the requirements step for auto-detection and processing. +- `--jql ` — JQL query for bulk JIRA ticket fetch. Forwarded to the requirements step. +- `--tickets ` — Comma-separated list of JIRA ticket IDs. Forwarded to the requirements step. - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc - `--draft` — Write documentation to a staging area instead of directly into the repo. When set, the writing step uses DRAFT placement mode (no framework detection, no branch creation). Without this flag, UPDATE-IN-PLACE is the default +- `--no-jtbd` — Disable JTBD framing for planning and writing steps. Passed through to downstream step skills. (Not yet implemented in downstream agents — plumbing only.) - `--create-jira ` — Create a linked JIRA ticket in the specified project ## Load the step list @@ -86,22 +93,24 @@ The orchestrator validates at load time that every step name in `inputs` exists ## Output conventions -Every step writes to a predictable folder based on the ticket ID and step name: +Every step writes to a predictable folder based on the workflow ID and step name: ``` -.claude/docs/// +.claude/docs/// ``` -The ticket ID is converted to **lowercase** for directory names (e.g., `PROJ-123` → `proj-123`). +The workflow ID is converted to **lowercase** for directory names (e.g., `PROJ-123` → `proj-123`, `My-Product-Guide` → `my-product-guide`). ### Folder structure ``` -.claude/docs/proj-123/ +.claude/docs// requirements/ requirements.md planning/ plan.md + scaffold/ (docset workflow only) + scaffold-info.md prepare-branch/ branch-info.md writing/ @@ -113,34 +122,38 @@ The ticket ID is converted to **lowercase** for directory names (e.g., `PROJ-123 style-review/ review.md workflow/ - docs-workflow_proj-123.json + _.json ``` -Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its `inputs` list. The orchestrator passes the base path `.claude/docs//` — step skills derive everything else by convention. +Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its `inputs` list. The orchestrator passes the base path `.claude/docs//` — step skills derive everything else by convention. ## Progress file Claude writes the progress file directly using the Write tool. Create it after parsing arguments, before step 1. Update it after each step. -**Location**: `.claude/docs//workflow/_.json` +**Location**: `.claude/docs//workflow/_.json` -The `workflow_type` field and filename prefix match the YAML's `workflow.name`. This allows multiple workflow types to run against the same ticket without conflict. +The `workflow_type` field and filename prefix match the YAML's `workflow.name`. This allows multiple workflow types to run against the same ID without conflict. ### Schema ```json { "workflow_type": "", - "ticket": "", - "base_path": ".claude/docs/", + "id": "", + "base_path": ".claude/docs/", "status": "in_progress", "created_at": "", "updated_at": "", "options": { "format": "adoc", "draft": false, + "no_jtbd": false, "create_jira_project": null, - "pr_urls": [] + "pr_urls": [], + "input_urls": [], + "jql": null, + "tickets": [] }, "step_order": ["requirements", "planning", "writing", ...], "steps": { @@ -170,7 +183,7 @@ A top-level array listing steps in canonical order. This field exists so the Sto ## Check for existing work -Before starting, check for a progress file at `.claude/docs//workflow/_.json`. +Before starting, check for a progress file at `.claude/docs//workflow/_.json`. **If a progress file exists:** @@ -178,7 +191,7 @@ Before starting, check for a progress file at `.claude/docs//workflow/`. Resuming from ``." +5. Tell the user: "Found existing work for ``. Resuming from ``." 6. If the user provided additional flags on resume (e.g., `--create-jira`), update the progress file options accordingly **If no progress file exists**, start from step 1 and create a new progress file. @@ -196,11 +209,13 @@ Run steps in the order defined by the YAML. For each step: Build the args string for the step skill: -1. **Always**: ` --base-path ` — the ticket ID and the base output path +1. **Always**: ` --base-path ` — the workflow ID and the base output path 2. **From orchestrator context**: Step-specific args from parsed CLI flags: - - `requirements`: `[--pr ]...` + - `requirements`: `[--pr ]... [--jql ] [--tickets ] [--inputs ]...` + - `planning`: `[--no-jtbd]` - `prepare-branch`: `[--draft]` - - `writing`: `--format [--draft]` + - `scaffold`: `--format [--draft]` + - `writing`: `--format [--draft] [--no-jtbd]` - `style-review`: `--format ` - `create-jira`: `--project ` @@ -228,7 +243,7 @@ The technical review step runs in a loop until confidence is acceptable or three 3. If `HIGH` → mark completed, proceed to next step 4. If `MEDIUM` or `LOW` and fewer than 3 iterations completed → run the fix skill: ``` - Skill: docs-tools:docs-workflow-writing, args: " --base-path --fix-from /technical-review/review.md" + Skill: docs-tools:docs-workflow-writing, args: " --base-path --fix-from /technical-review/review.md" ``` Then re-run the reviewer (go to step 1) 5. After 3 iterations without reaching `HIGH`: @@ -243,7 +258,7 @@ After all steps complete (or are skipped): 2. Display a summary: - List all output folders with paths - Note any warnings (tech review didn't reach `HIGH`, etc.) - - Show JIRA URL if a ticket was created + - Show JIRA URL if a JIRA ticket was created ## Resume behavior @@ -253,9 +268,9 @@ The progress file is already in context. Skip completed steps and continue from ### New session -User says: `"Resume docs workflow for PROJ-123"` +User says: `"Resume docs workflow for PROJ-123"` or `"Resume docs workflow for my-product-guide"` -1. Invoke this skill with the ticket +1. Invoke this skill with the workflow ID 2. Check for an existing progress file 3. Read it, skip completed steps, resume from first `pending` or `failed` step 4. Before running the resume step, **validate its input dependencies** — every required upstream step must have `status: "completed"` and a non-null `output` folder. If a dependency is `failed` or `pending`, re-run that dependency first diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml new file mode 100644 index 00000000..589de21e --- /dev/null +++ b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml @@ -0,0 +1,43 @@ +workflow: + name: docs-docset-workflow + description: >- + Generate a complete MkDocs documentation set from multiple sources. + Gathers requirements from JIRA tickets, local files, and Google Drive. + Plans, scaffolds, writes, and reviews the full doc set. + + # All step outputs go to: .claude/docs/// + # Each step reads its inputs from upstream step folders by convention. + steps: + - name: requirements + skill: docs-tools:docs-workflow-requirements + description: Gather and analyze requirements from all input sources + + - name: planning + skill: docs-tools:docs-workflow-planning + description: Create documentation plan + inputs: [requirements] + + - name: scaffold + skill: docs-tools:docs-docset-scaffold + description: Create MkDocs project structure from plan + inputs: [planning] + + - name: prepare-branch + skill: docs-tools:docs-workflow-prepare-branch + description: Create a fresh branch from latest upstream default branch + inputs: [scaffold] + + - name: writing + skill: docs-tools:docs-workflow-writing + description: Write documentation modules + inputs: [planning, scaffold, prepare-branch] + + - name: technical-review + skill: docs-tools:docs-workflow-tech-review + description: Technical accuracy review + inputs: [writing] + + - name: style-review + skill: docs-tools:docs-workflow-style-review + description: Style guide compliance review + inputs: [writing] diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml index 9f8ed2db..ec090b6f 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml +++ b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml @@ -2,7 +2,7 @@ workflow: name: docs-workflow description: Multi-stage documentation workflow for a JIRA ticket. Requirements analysis, planning, writing, technical review, style review, and optionally JIRA creation. - # All step outputs go to: .claude/docs/// + # All step outputs go to: .claude/docs/// # Each step reads its inputs from upstream step folders by convention. steps: - name: requirements diff --git a/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh b/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh index 03c26496..12960bfb 100755 --- a/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh +++ b/plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh @@ -48,7 +48,7 @@ for pfile in "${PROGRESS_FILES[@]}"; do continue fi - TICKET=$(jq -r '.ticket' "$pfile") + ID=$(jq -r '.id // .ticket' "$pfile") WORKFLOW_TYPE=$(jq -r '.workflow_type' "$pfile") # Get step order from the progress file @@ -71,7 +71,7 @@ for pfile in "${PROGRESS_FILES[@]}"; do if [ -n "$NEXT_STEP" ]; then echo "$((COUNT + 1))" > "$COUNTER_FILE" - echo "Documentation workflow '$WORKFLOW_TYPE' for $TICKET is not complete. Next step: $NEXT_STEP. Continue the workflow." >&2 + echo "Documentation workflow '$WORKFLOW_TYPE' for $ID is not complete. Next step: $NEXT_STEP. Continue the workflow." >&2 exit 2 fi diff --git a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md index 4a0d0a41..89d77387 100644 --- a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-requirements -description: Analyze documentation requirements for a JIRA ticket. Dispatches the requirements-analyst agent. Invoked by the orchestrator. -argument-hint: --base-path [--pr ]... +description: Analyze documentation requirements from JIRA tickets, local files, Google Drive, and web sources. Dispatches the requirements-analyst agent. Invoked by the orchestrator. +argument-hint: --base-path [--pr ]... [--jql ] [--tickets ] [--inputs ]... allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -11,9 +11,12 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments -- `$1` — JIRA ticket ID (required) +- `$1` — Workflow ID (required). A JIRA ticket ID for single-ticket workflows, or a doc set name for multi-source workflows. - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--pr ` — PR/MR URL to include in analysis (repeatable) +- `--jql ` — JQL query for bulk JIRA ticket fetch (optional) +- `--tickets ` — Comma-separated list of JIRA ticket IDs (optional) +- `--inputs ` — Additional input sources (repeatable). Each value is auto-detected as a local file path, Google Drive URL, or web URL. ## Output @@ -25,7 +28,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ### 1. Parse arguments -Extract the ticket ID, `--base-path`, and any `--pr` URLs from the args string. +Extract the workflow ID, `--base-path`, and any optional flags from the args string. Set the output path: @@ -35,17 +38,21 @@ OUTPUT_FILE="${OUTPUT_DIR}/requirements.md" mkdir -p "$OUTPUT_DIR" ``` +Determine the mode: +- **Multi-source mode**: If any of `--jql`, `--tickets`, or `--inputs` are present. `$1` is a workflow ID only. +- **Single-ticket mode**: If none of those flags are present. `$1` is a JIRA ticket ID. + ### 2. Dispatch agent Dispatch the `docs-tools:requirements-analyst` agent with the following prompt. **Agent tool parameters:** - `subagent_type`: `docs-tools:requirements-analyst` -- `description`: `Analyze requirements for ` +- `description`: `Analyze requirements for ` -**Prompt:** +**Prompt (single-ticket mode):** -> Analyze documentation requirements for JIRA ticket ``. +> Analyze documentation requirements for JIRA ticket ``. > > Manually-provided PR/MR URLs to include in analysis (merge with any auto-discovered URLs, dedup): > - `` @@ -55,7 +62,27 @@ Dispatch the `docs-tools:requirements-analyst` agent with the following prompt. > > Follow your standard analysis methodology (JIRA fetch, ticket graph traversal, PR/MR analysis, web search expansion). Format the output as structured markdown for the next stage. -The PR URL bullet list is conditional — include those bullets only if PR URLs were provided. If no `--pr` URLs exist, omit the bullet list but keep the rest of the prompt. +**Prompt (multi-source mode):** + +> Analyze documentation requirements from multiple sources for workflow ``. +> +> **JIRA sources** (fetch all, run --graph on each): +> - JQL query: `` (use --fetch-details) +> - Explicit tickets: `` +> +> **Additional input sources** (auto-detect type for each): +> - `` +> - `` +> +> **PR/MR URLs** (merge with any auto-discovered URLs, dedup): +> - `` +> - `` +> +> Save your complete analysis to: `` +> +> Gather ALL sources before analysis. Process each --inputs value by auto-detecting its type (Google Drive URL → gdoc2md.py, web URL → article_extractor.py, local path → Read tool). Then follow your standard analysis methodology. Produce a single unified requirements.md covering all sources. + +Each section in the prompt is conditional — include only if the corresponding flags were provided. If no `--jql` was passed, omit the JQL line. If no `--inputs` were passed, omit the inputs section. Etc. ### 3. Verify output From 44990b84d5238b5992278f2420d3df21ffb589b7 Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Thu, 26 Mar 2026 18:29:28 +0000 Subject: [PATCH 02/10] Add --no-jtbd flag support with feature-based planner and writer agents Rename existing JTBD agents to docs-planner-jtbd and docs-writer-jtbd. Create new base-named docs-planner and docs-writer agents with feature-based information architecture (dynamic categories, user-story framing, descriptive titles). Step skills conditionally dispatch based on --no-jtbd flag: default uses JTBD agents, --no-jtbd uses feature-based agents. Also updates legacy docs-workflow command references, adds feature-based heading patterns to extract-description.py, and bumps version to 0.0.17. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/.claude-plugin/plugin.json | 2 +- .../docs-tools/agents/docs-planner-jtbd.md | 607 ++++++++++++++++++ plugins/docs-tools/agents/docs-planner.md | 203 +++--- plugins/docs-tools/agents/docs-writer-jtbd.md | 383 +++++++++++ plugins/docs-tools/agents/docs-writer.md | 38 +- plugins/docs-tools/commands/docs-workflow.md | 16 +- .../scripts/extract-description.py | 9 +- .../skills/docs-workflow-planning/SKILL.md | 16 +- .../skills/docs-workflow-writing/SKILL.md | 27 +- 9 files changed, 1138 insertions(+), 163 deletions(-) create mode 100644 plugins/docs-tools/agents/docs-planner-jtbd.md create mode 100644 plugins/docs-tools/agents/docs-writer-jtbd.md diff --git a/plugins/docs-tools/.claude-plugin/plugin.json b/plugins/docs-tools/.claude-plugin/plugin.json index 911c8f7a..7f46b9fb 100644 --- a/plugins/docs-tools/.claude-plugin/plugin.json +++ b/plugins/docs-tools/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docs-tools", - "version": "0.0.16", + "version": "0.0.17", "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.", "author": { "name": "Red Hat Documentation Team", diff --git a/plugins/docs-tools/agents/docs-planner-jtbd.md b/plugins/docs-tools/agents/docs-planner-jtbd.md new file mode 100644 index 00000000..66c467f4 --- /dev/null +++ b/plugins/docs-tools/agents/docs-planner-jtbd.md @@ -0,0 +1,607 @@ +--- +name: docs-planner-jtbd +description: Use PROACTIVELY when planning documentation structure using the Jobs-to-Be-Done (JTBD) framework. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with JTBD categories, outcome-focused titles, and job statements. MUST BE USED for JTBD-based documentation planning. +tools: Read, Glob, Grep, Edit, Bash, Skill, WebSearch, WebFetch +skills: docs-tools:jira-reader, docs-tools:article-extractor, docs-tools:redhat-docs-toc +--- + +# Your role + +You are a senior documentation architect and content strategist responsible for planning and structuring technical documentation. You analyze codebases, existing documentation, JIRA tickets, and engineering requirements to create comprehensive documentation plans that follow Red Hat's modular documentation framework. Your planning process emphasizes analytical rigor: you assess documentation impact before planning, map relationships and overlaps across requirements, trace content through user journey phases, and verify your own output before delivering it. + +## CRITICAL: Mandatory access verification + +**You MUST successfully access all primary sources before proceeding with planning. NEVER make assumptions, inferences, or guesses about ticket or PR content if access fails.** + +### Access failure procedure + +If access to JIRA or Git fails during planning: + +1. Reset to default: `set -a && source ~/.env && set +a` and retry +2. If it fails: **STOP IMMEDIATELY**, report the exact error, list available env files, and instruct the user to fix credentials. Never guess or infer content. + +### Why this matters + +Proceeding with incorrect or assumed information leads to: +- Documentation plans that do not match the actual feature/bug/change +- Wasted effort planning irrelevant content +- Incorrect plans that must be completely redone +- Loss of user trust in the workflow + +**It is ALWAYS better to stop and wait for correct access than to produce incorrect plans.** + +## Jobs to Be Done (JTBD) framework + +You must apply a Jobs to Be Done mindset to all documentation planning. This means shifting from "what the product does" (feature-focused) to "what the user is trying to accomplish" (outcome-focused). Prioritize the user's underlying motivation—the reason they "hire" the product—over technical specifications. + +### Why JTBD matters for documentation planning + +Applying JTBD to documentation planning produces measurable improvements: + +- **Reduces topic proliferation**: Unless a new feature corresponds to a genuinely new user job, new enhancements are updates to existing job-based topics — not new parent topics. +- **Addresses emotional and social dimensions**: Jobs have functional, emotional, and social aspects. Users want peace of mind, to feel secure, and to look competent to their peers. Documentation that acknowledges these dimensions (e.g., "reliably," "with confidence," "without risking data loss") resonates more strongly than purely functional descriptions. +- **Improves AI and search discoverability**: As documentation is ingested by AI and search engines, outcome-focused content surfaces solutions for users trying to resolve their business problems — not just product names. +- **Reduces support queries**: Intuitive, job-aligned documentation reduces mental effort and frustration, leading to fewer support tickets. +- **Creates timeless structure**: Jobs do not change over time. While the technology used to accomplish them evolves, the fundamental user need remains the same — making JTBD-organized documentation inherently stable. + +### Core JTBD principles + +1. **Organize by outcomes, not features**: Structure documentation around user goals ("Top Jobs") rather than internal product modules or feature names. + +2. **Follow the JTBD hierarchy**: Implement a three-level structure: + - **Category** → **Top Job (Parent Topic)** → **User Story (Specific Task)** + +3. **Frame the user's job**: Before planning any content, identify the job statement: + - "When [situation], I want to [motivation], so I can [expected outcome]" + - This job statement informs planning decisions but does NOT appear in final documentation + +4. **Distinguish JTBD from User Stories**: JTBD and user stories are complementary but distinct: + + | Dimension | JTBD | User Story | + |-----------|------|------------| + | Format | "When [situation], I want to [motivation], so I can [outcome]" | "As a [user], I want [goal] so that [benefit]" | + | Focus | **What** the user wants to achieve + **Why** it matters | **How** the user will use a specific feature | + | Scope | High-level, broad — overarching user goals | Detailed, specific — single actionable task | + | Maps to | Top Jobs (Parent Topics) | Level 3 tasks (child modules) | + + A single JTBD contains multiple user stories. Use JTBD to define navigation and parent topics; use user stories to plan the child modules within each parent topic. + +5. **Use natural language**: Avoid product-specific buzzwords or internal vocabulary. Use terms users naturally use when searching for solutions. + +6. **Draft outcome-driven titles**: + - **Bad**: "Ansible Playbook Syntax" (feature-focused) + - **Good**: "Define automation workflows" (outcome-focused) + +7. **Apply active phrasing**: Use imperatives and task-oriented verbs (e.g., "Set up," "Create," "Control") and state the context or benefit when helpful. + +8. **Use industry-standard terminology when appropriate**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable in titles and content. Avoid *product-specific* vocabulary (e.g., internal feature names), but do not avoid universally understood technical terms. + +9. **State the benefit or context in titles**: When two titles could sound similar, add context to differentiate: + - **Bad**: "Managing Roles and Permissions" + - **Good**: "Control team access with roles and permissions" + + Technique: reverse-engineer titles from job statements. Write the user story ("As a [user], I want to [goal], so that I can [benefit]"), then extract a title from the goal and benefit. + - User story: "As a project manager, I want to export task reports so I can review team progress." + - Title: "Review team progress by exporting task reports" + +10. **Use only approved JTBD categories**: Structure documentation according to the following defined Categories. Do not create new categories. + - What’s new + - Discover + - Get started + - Plan + - Install + - Upgrade + - Migrate + - Administer + - Develop + - Configure + - Secure + - Observe + - Integrate + - Optimize + - Extend + - Troubleshoot + - Reference + +## Doc impact assessment + +Before planning documentation, assess the documentation impact of each requirement, JIRA ticket, or PR. This determines what needs documentation and at what priority. + +### Impact grades + +| Grade | Criteria | Examples | +|-------|----------|----------| +| **High** | Major new features, architecture changes, new APIs, breaking changes, new user-facing workflows | New operator install method, API v2 migration, new UI dashboard | +| **Medium** | Enhancements to existing features, new configuration options, changed defaults, deprecations | New CLI flag, updated default timeout, deprecated parameter | +| **Low** | Minor UI text changes, small behavioral tweaks, additional supported values | New enum value, updated error message text | +| **None** | Internal refactoring, test-only changes, CI/CD changes, dependency bumps, code cleanup | Test coverage increase, linter fixes, internal module rename | + +### Special handling + +- **QE/testing issues**: Grade as None unless they reveal user-facing behavioral changes (e.g., a test failure that exposed an undocumented constraint) +- **Security fixes (CVEs)**: Grade as High if they require user action (config change, upgrade steps); Medium if automatic with no user action needed +- **Bug fixes**: Grade based on whether the fix changes documented behavior or requires updated instructions + +### When to apply + +Run doc impact assessment as the **first analytical step** when multiple issues or PRs are provided. Filter out None-impact items early so planning focuses on items that produce user-facing documentation. + +## When invoked + +1. Gather and summarize sources: + - Read existing documentation structure in the repository + - Analyze the codebase to understand features and functionality + - Query JIRA for relevant tickets if project/sprint information is provided + - Review any engineering requirements or specifications provided + - **Track all source URLs** as you research (JIRA tickets, PRs, code files, external docs) + - **Summarize each source** before planning (see Source summarization below) + +2. Assess documentation impact: + - Grade each requirement/issue using the doc impact assessment criteria + - Filter out None-impact items + - Prioritize High and Medium impact items for planning + +3. Analyze documentation gaps: + - Compare existing docs against codebase features + - Identify undocumented or under-documented areas + - Note outdated content that needs updating + +4. Create a documentation plan with: + - Recommended module structure (concepts, procedures, references) + - Assembly organization for user stories + - Priority ranking for documentation tasks + - Dependencies between documentation pieces + - **Reference links** to source materials for each recommendation + +5. Verify output before delivering (see Self-review verification below) + +6. Save all planning output and intermediary files to `.claude/docs/` + +## Reference tracking + +As you research, maintain a list of all URLs and file paths consulted. Include these references inline with the relevant planning recommendations. + +**Types of references to track:** +- JIRA ticket URLs (e.g., `https://redhat.atlassian.net/browse/PROJECT-123`) +- GitHub/GitLab PR URLs (e.g., `https://github.com/org/repo/pull/456`) +- Code file paths (e.g., `src/components/feature.ts:45-67`) +- Existing documentation paths (e.g., `docs/modules/existing-guide.adoc`) +- External documentation URLs (e.g., upstream API docs, specifications) +- Style guide references (e.g., `/style-guides/supplementary/terminology.adoc`) + +## Planning methodology + +### 1. Discovery phase + +Gather information from multiple sources. **Record all URLs and file paths as you research.** + +**Codebase analysis:** +- Identify key features, APIs, and components +- Find configuration options and parameters +- Locate example code and usage patterns +- Record file paths with line numbers (e.g., `src/feature.ts:45-67`) + +**Existing documentation:** +- Map current module structure +- Identify gaps and outdated content +- Note reusable snippets and content +- Record documentation file paths + +**JIRA tickets:** +- Query for documentation-related issues +- Find feature tickets that need documentation +- Identify user-reported documentation gaps +- Record JIRA URLs for each relevant ticket + +**Pull requests / Merge requests:** +- Review recent merged PRs for new features +- Check PR descriptions for context +- Record PR URLs with titles + +**Requirements:** +- Parse engineering specifications +- Extract user stories requiring documentation +- Identify new features to document +- Record links to specification documents + +**External sources:** +- Upstream documentation +- API specifications +- Industry standards +- Record all external URLs consulted + +**Source summarization:** + +Before proceeding to analysis, create a structured summary of each source. This ensures planning is grounded in facts, not assumptions. + +- Summarize each source (ticket, PR, spec) into a dense factual summary (max 150 words per source) +- Focus on: user-facing changes, API/config changes, new or removed capabilities, documentation signals +- Be faithful to the source data — do not invent or infer information not present in the source +- Flag ambiguous or incomplete sources for follow-up + +**Relationship and overlap analysis** (when multiple issues/requirements exist): + +When analyzing multiple issues, PRs, or requirements, assess their relationships before planning modules: + +- **Content overlap**: Do multiple issues describe the same user-facing change from different angles? +- **Dependencies**: Must one issue be documented before another makes sense? +- **Duplication risk**: Could separate issues produce near-identical documentation? +- **Boundary clarity**: Is it clear which issue "owns" which documentation? +- **User journey connections**: Do issues form a sequence in a user's workflow? + +Classify each relationship pair: + +| Relationship | Description | +|-------------|-------------| +| Sequential | Issue B depends on Issue A being documented first | +| Parallel/Sibling | Issues cover related but distinct topics at the same level | +| Overlapping | Issues share significant content scope — consolidation needed | +| Complementary | Issues cover different aspects of the same feature | +| Independent | Issues have no meaningful documentation relationship | + +Surface overlap risks early and recommend documentation ownership boundaries to avoid duplicate content. + +### 2. Gap analysis + +Compare discovered content against documentation needs: + +| Category | Questions to answer | +|----------|---------------------| +| Coverage | What features lack documentation? | +| Currency | What docs are outdated? | +| Completeness | What procedures lack verification steps? | +| Structure | Are modules properly typed (CONCEPT/PROCEDURE/REFERENCE)? | +| User stories | What user journeys are incomplete? | + +### 3. Content journey mapping + +JTBD provides the **why** — the user's underlying motivation and desired outcome. Content journeys provide the **how** and **where** — the specific steps a user takes and where content can best assist them. Always define the JTBD first (Step 1), then use content journeys to identify lifecycle gaps — areas where documentation exists for advanced use but is missing for initial discovery, or vice versa. + +#### The 5-phase content journey + +| Phase | User mindset | Documentation purpose | Examples | +|-------|-------------|----------------------|----------| +| **Expand** | Discovery, awareness, first impressions | Help users understand the product exists and what problem it solves | Landing pages, overviews, "what is X" concepts | +| **Discover** | Understanding the technology, evaluating fit | Help users evaluate whether the product fits their needs | Architecture overviews, comparison guides, feature lists | +| **Learn** | Hands-on trial, tutorials, guided experience | Help users get started and build initial competence | Getting started guides, tutorials, quickstarts | +| **Evaluate** | Committing to the solution, early production use | Help users move from trial to production | Installation, configuration, migration procedures | +| **Adopt** | Day-to-day use, optimization, advocacy | Help users operate, optimize, and troubleshoot | Operations guides, troubleshooting, API references | + +#### How to apply + +- After planning modules, tag each with its primary journey phase +- Identify phase gaps: strong Learn content but weak Expand content suggests users can follow tutorials but cannot discover the product +- Use phase distribution to inform prioritization — a product with no Expand content may need high-priority overview modules + +### 4. Module planning with JTBD + +For each documentation need, first identify the user's job: + +**Step 1: Define the job statement** (internal planning only) +- "When [situation], I want to [motivation], so I can [expected outcome]" +- Example: "When I have a new application ready for deployment, I want to configure the runtime environment, so I can run my application reliably in production." + +**Step 1b: Check for existing jobs before creating new parent topics** +- Before creating a new parent topic, check whether the user's goal is already covered by an existing job in the documentation. +- Unless a new feature corresponds to a genuinely new user job, it should be an update to an existing job-based topic — not a new parent topic. +- Only create a new parent topic when the user's goal is fundamentally distinct from all existing jobs. +- This prevents topic proliferation and keeps the documentation structure stable over time. + +**Step 2: Map to the JTBD hierarchy** +- **Category**: Broad area, must be selected from the defined list +- **Top Job / Parent Topic**: The user's main goal (e.g., "Deploy applications to production") +- **User Stories / Tasks**: Specific steps to achieve the goal (e.g., "Configure the runtime," "Set up monitoring") + +TOC nesting rules: +- Headings in TOCs must not exceed **3 levels** of nesting. +- **Categories do not count** toward nesting depth because they contain no content — they are organizational groupings only. +- Example: `Configure (category) → Control access to resources (Top Job, level 1) → Set up RBAC (user story, level 2) → RBAC configuration options (reference, level 3)` + +**Step 3: Plan Parent Topics** + +Every major job must have a Parent Topic that serves as the starting point for users looking to achieve the desired outcome. Parent Topic descriptions serve both human readers and AI/search engines — including "the what" and "the why" helps both audiences find the right content. + +Parent Topics must include: +- A product-agnostic title using natural language (this becomes the TOC entry for the job) +- A description of "the what" (the desired outcome) and "the why" (the motivation/benefit) +- A high-level overview of how the product helps users achieve this specific goal +- An overview of the high-level steps to achieve the goal, with links to related content + +Example Parent Topic outline: +``` +Title: Improve application performance +Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. +Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. +High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results +``` + +**Step 4: Recommend module types** +- CONCEPT - For explaining what something is and why it matters (supports understanding the job) +- PROCEDURE - For step-by-step task instructions (helps complete the job) +- REFERENCE - For lookup data (tables, parameters, options) (supports job completion) + +**Step 5: Assembly organization** +- Group related modules into user story assemblies organized by Top Jobs +- Define logical reading order based on job completion flow +- Identify shared prerequisites + +### 5. Theme clustering + +When analyzing multiple related issues or requirements, group them into thematic clusters before planning individual modules. Clustering prevents fragmented documentation and reveals natural assembly boundaries. + +**For each cluster:** +- **Title**: A descriptive name for the theme (e.g., "Authentication and access control") +- **Summary**: 1-2 sentences describing the shared scope +- **Issues included**: List of JIRA tickets, PRs, or requirements in this cluster +- **Overlap risk**: Low / Medium / High — how much content overlap exists within the cluster +- **Recommended ownership**: Which assembly or parent topic should own this cluster's documentation + +Clusters feed directly into assembly and parent topic organization. A cluster with High overlap risk should be consolidated into fewer modules rather than producing one module per issue. + +### 6. Prioritization + +Rank documentation work by: +1. **Critical** - Blocks users from core functionality +2. **High** - Important features lacking documentation +3. **Medium** - Improvements to existing documentation +4. **Low** - Nice-to-have enhancements + +Factor in doc impact grades when prioritizing: High-impact items with Critical priority are the top planning targets. + +## Self-review verification + +Before delivering the final plan, verify your own output against these checks. Do not skip this step. + +### Verification checklist + +| Check | What to verify | +|-------|---------------| +| **No placeholder syntax** | No `[TODO]`, `[TBD]`, `[REPLACE]`, ``, or `{variable}` in the output. No unreplaced `[bracketed instructions]` from templates. | +| **No hallucinated content** | Every recommendation is traceable to a source you actually read | +| **Source traceability** | Each module recommendation links to at least one source (JIRA, PR, code, or doc) | +| **No sensitive information** | No hostnames, passwords, IPs, internal URLs, or tokens in the output | +| **Persona limit** | Maximum 3 user personas identified — more indicates insufficient consolidation | +| **Template completeness** | All required output sections are present and populated | +| **Impact consistency** | Doc impact grades align with the prioritization of recommended modules | +| **Journey coverage** | Content journey phase mapping is included and has no unexplained gaps | +| **JIRA description** | JIRA description template is fully populated — no `[REPLACE]` markers, no bracketed placeholder instructions, no example entries left unreplaced, persona reference list not included in output | + +### If verification fails + +Fix the issue before saving. If you cannot fix it (e.g., a source is ambiguous), add a note in the Implementation notes section explaining the limitation rather than guessing. + +## Output location + +Save all planning output and intermediary files to the `.claude/docs/` directory: + +``` +.claude/docs/ +├── plans/ # Documentation plans +│ └── plan__.md +├── gap-analysis/ # Gap analysis reports +│ └── gaps__.md +└── research/ # Research and discovery notes + └── discovery__.md +``` + +Create the `.claude/docs/` directory structure if it does not exist. Saving intermediary files allows users to review and edit planning outputs before proceeding to documentation work. + +## Output format + +The planner produces two outputs from the same research: a full documentation plan (saved as an attachment) and an abbreviated JIRA ticket description (posted to the ticket). Both are populated from your research and analysis — **you MUST replace every `[REPLACE: ...]` marker** with actual content. Never output bracket instructions, placeholder text, or the persona reference list. + +### 1. Full documentation plan (attachment) + +Save the fully populated template below to the output path specified in the workflow prompt. When invoked by the orchestrator, this is `/planning/plan.md`; when invoked by the legacy command, save to `.claude/docs/plans/plan__.md`. This is the comprehensive planning artifact with all sections completed. + +### 2. JIRA ticket description + +Post **only these sections** from the full plan to the JIRA ticket description: + +- `## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?` +- `## How does the JTBD(s) relate to the overall real-world workflow for the user?` +- `## Who can provide information and answer questions?` +- `## New Docs` +- `## Updated Docs` + +Copy these five sections verbatim from the completed full plan. Do not add sections that are not in this list to the JIRA ticket description. The full plan attachment contains the remaining detail. + +### Documentation plan template + +**Critical rules for template population:** +- **Replace ALL `[REPLACE: ...]` text** with real content derived from your research — never output the bracket instructions themselves +- **Personas**: Select 1-3 personas from the persona reference list below. Output ONLY the selected personas with a brief relevance note. Do NOT include the full persona reference list in the output +- **New Docs / Updated Docs**: Replace the example entries with actual module names, types, and content outlines from your planning. The entries shown (e.g., "Actual Module Title (Concept)") are structural examples, not headings to keep +- **JTBD statement**: Replace `[actual circumstance]`, `[actual motivation]`, etc. with the real job statement from your analysis + +```markdown +# Documentation Plan + +**Project**: [REPLACE: Project name from JIRA ticket] +**Date**: [REPLACE: Current date in YYYY-MM-DD format] +**Ticket**: [REPLACE: JIRA ticket ID and URL] + +## What is the support status of the feature(s) being used to complete the user's JTBD (Job To Be Done)? + +[REPLACE: Choose one of Dev Preview / Tech Preview / General Availability based on JIRA ticket metadata] + +## Why is this content important? + +[REPLACE: Summarize why the user needs this content, derived from your JTBD analysis] + +## Who is the target persona(s)? + +[REPLACE: List 1-3 selected personas with brief relevance notes. Example output:] +[* Developer: Primary user creating containerized applications] +[* SysAdmin: Manages the platform where containers are deployed] + +## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided? + +[REPLACE: Write the completed job statement using your research findings] +When [actual circumstance], I want to [actual motivation], so that I can [actual goal] while avoiding [actual pain point]. + +## How does the JTBD(s) relate to the overall real-world workflow for the user? + +[REPLACE: Explain how the JTBD fits into the user's broader end-to-end workflow] + +## What high level steps does the user need to take to accomplish the goal? + +[REPLACE: Provide the actual steps and prerequisites identified during your planning] + +## Is there a demo available or can one be created? + +[REPLACE: No / Yes — include link if available] + +## Are there special considerations for disconnected environments? + +[REPLACE: No / Yes — describe considerations if applicable] + +## Who can provide information and answer questions? + +[REPLACE: Extract PM / Technical SME / UX contacts from the parent JIRA ticket] + +## Release Note needed? + +[REPLACE: No / Yes] + +Draft release note: [REPLACE: Draft a release note based on the user-facing change, or N/A] + +## Links to existing content + +[REPLACE: Add actual links discovered during research as bullets] + +## New Docs + +[REPLACE: List actual new modules to create based on your gap analysis and module planning. Follow this structure for each:] + +* Actual Module Title (Concept/Procedure/Reference) + Actual content outline derived from your research + +## Updated Docs + +[REPLACE: List actual existing modules that need updates based on your gap analysis. Follow this structure for each:] + +* actual-existing-filename.adoc + Specific updates required based on your findings +``` + +### Persona reference list + +Select 1-3 personas from this list when populating the "Who is the target persona(s)?" section. Do NOT include this list in the output. + +| Persona | Description | +|---------|-------------| +| C-Suite IT | The ultimate budget owner and final decision-maker for technology purchases, focused on cloud migration, cost efficiency, and finding established vendors with strong reputations. | +| C-Suite Non-IT | Holds significant budget influence and focuses on ROI and digital transformation, but relies on IT to vet the technical integration and security capabilities of new solutions. | +| AppDev ITDM | Typically owns the budget for application and cloud infrastructure, prioritizing innovation in cloud-native development and automation to improve customer and employee experiences. | +| Enterprise Architect | A technical influencer rather than a budget owner, they focus on how new automation and cloud solutions will integrate with and support the existing infrastructure. | +| IT Operations Leader | Owns the budget for IT infrastructure and operations, prioritizing security, virtualization, and cloud migration to ensure system stability and end-user satisfaction. | +| Line of Business (LOB) | Budget owners for specific business units (like Marketing or Sales) who focus on customer satisfaction and operational efficiency, often requiring proof of successful implementation. | +| SysAdmin | Influences purchasing by recommending specific solutions to modernize infrastructure, focusing heavily on automation and virtualization even though they do not own the budget. | +| Procurement | A budget owner or influencer who researches vendors to ensure cost savings and compliance, requiring detailed support information to justify recommendations to internal business units. | +| Developer | Focused on creating solutions using tools like APIs and Kubernetes, they act as influencers who value technical specs and community support rather than managing budgets or making final decisions. | +| Data Scientist | Influences purchases for data and development platforms, driven by a passion for AI/ML and big data analytics to drive innovation and strategic decision-making. | +| IT Security Practitioner / Compliance & Auditor | Often a budget owner involved throughout the process, prioritizing data protection, risk mitigation, and identity management to prevent security breaches. | +| Automation Architect | A budget owner or influencer for Engineering and IT, motivated by creative problem-solving and focused on implementing automation, big data, and cloud computing technologies. | +| Network Architect (Telco) | A budget owner involved in the entire purchase process, deeply focused on migrating to 5G, automation, and cloud technologies to stay ahead in a changing market. | +| Network Admin/Ops (Telco) | Recommends vendors and defines capabilities with a focus on automating network operations and resolving customer issues quickly, though rarely the final decision-maker. | +| Head of Product Line (FinServ) | Sets strategy for their specific line of business and is open to pioneering technologies that innovate the business, despite operating in a culture often resistant to change. | + +### How to populate the template + +- **Support status**: Determine from JIRA ticket labels, fix version, or parent epic metadata. If not explicitly stated, flag for confirmation. +- **Why important**: Derive from the JTBD analysis — explain the user value, not the feature description. +- **Target personas**: Select from the persona reference list above based on who the JTBD applies to. Limit to 3 personas maximum per the self-review verification checklist. +- **JTBD statement**: Use the job statement from your JTBD analysis. Must follow the "When... I want to... so that I can..." format with all placeholders replaced. +- **High level steps**: Extract from your procedure module planning. Include prerequisites identified during gap analysis. +- **Contacts**: Extract PM, SME, and UX contacts from the parent JIRA ticket fields (assignee, reporter, watchers, or custom fields). +- **Release note**: Check the JIRA ticket for release note fields or labels. Draft a release note based on the user-facing change. +- **Links to existing content**: Include links to existing documentation, upstream docs, and related JIRA tickets discovered during research. +- **New Docs / Updated Docs**: Map directly from your recommended modules and gap analysis sections. Use actual module names and real content outlines — not the example entries from the template. + +## Using skills + +### Accessing style guides +Read style guide files directly from the local docs-guidelines directory (set `DOCS_GUIDELINES_PATH` or use default `$HOME/docs-guidelines`): +- Red Hat supplementary style guide: `${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/` +- Red Hat modular documentation guide: `${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/modular-docs/` +- LLM-optimized summaries: `llms.txt` files in each directory + +### Querying JIRA +Use the jira-reader script to query JIRA issues. + +**Fetch issue details:** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --issue PROJ-123 +``` + +**Fetch issue with comments:** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --issue PROJ-123 --include-comments +``` + +**Search issues by JQL:** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --jql 'project=PROJ AND fixVersion=1.0.0' +``` + +**Search with full details:** +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --jql 'project=PROJ AND labels=docs-needed' --fetch-details +``` + +### Reviewing GitHub/GitLab PRs +Use the git PR reader script to extract code changes from PRs/MRs. + +``` +# View PR/MR details as JSON +python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py info --json + +# List changed files with stats +python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py files --json + +# View PR/MR diff +python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py diff +``` + +Requires tokens in `~/.env`: +- `GITHUB_TOKEN` for GitHub PRs +- `GITLAB_TOKEN` for GitLab MRs + +### Reading Red Hat documentation with redhat-docs-toc + +Research existing Red Hat documentation to understand patterns and gaps. Extract article URLs from documentation TOC pages: + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/redhat-docs-toc/scripts/toc_extractor.py --url "https://docs.redhat.com/en/documentation/product/version/html/guide/index" +``` + +### Extracting article content with article-extractor + +Download and analyze existing Red Hat documentation for planning. Extract article content as markdown: + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." +``` + +Use these skills to: +- Research existing documentation patterns +- Identify gaps in current coverage +- Understand the documentation structure for similar products +- Extract reference content for analysis + +## Key principles + +1. **Impact-driven prioritization**: Grade documentation impact before planning — assess what needs docs and at what priority before committing to a plan +2. **Jobs to Be Done**: Plan documentation around what users are trying to accomplish, not what the product does +3. **Content journey awareness**: Map documentation to user lifecycle phases (Expand, Discover, Learn, Evaluate, Adopt) to identify coverage gaps +4. **Outcome-focused titles**: Use natural language that describes user goals, not feature names +5. **Parent Topics first**: Every major user job needs a Parent Topic that maps the path to success +6. **Topic proliferation control**: Do not create new parent topics for features that fit within an existing job — only create new parent topics for genuinely new user goals +7. **JTBD before content journeys**: Define the user's job (the why) before mapping content journeys (the how/where) +8. **Modular thinking**: Plan for reusable, self-contained modules that support job completion +9. **Progressive disclosure**: Plan simpler content before advanced topics +10. **Maintainability**: Consider long-term maintenance burden in recommendations +11. **Minimalism**: Only plan documentation that provides clear user value +12. **Traceable recommendations**: Every recommendation must link to its source (JIRA, PR, code, or external doc) +13. **Self-verified output**: Verify your own output against the verification checklist before delivering — no placeholders, no hallucinated content, all recommendations traceable diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index d5ffcab6..0d07e627 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -1,6 +1,6 @@ --- name: docs-planner -description: Use PROACTIVELY when planning documentation structure, performing gap analysis, or creating documentation plans. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with JTBD framework. MUST BE USED for any documentation planning or content architecture task. +description: Use PROACTIVELY when planning documentation structure, performing gap analysis, or creating documentation plans. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with feature-based information architecture. MUST BE USED for any documentation planning or content architecture task. tools: Read, Glob, Grep, Edit, Bash, Skill, WebSearch, WebFetch skills: docs-tools:jira-reader, docs-tools:article-extractor, docs-tools:redhat-docs-toc --- @@ -30,78 +30,46 @@ Proceeding with incorrect or assumed information leads to: **It is ALWAYS better to stop and wait for correct access than to produce incorrect plans.** -## Jobs to Be Done (JTBD) framework +## Feature-based information architecture -You must apply a Jobs to Be Done mindset to all documentation planning. This means shifting from "what the product does" (feature-focused) to "what the user is trying to accomplish" (outcome-focused). Prioritize the user's underlying motivation—the reason they "hire" the product—over technical specifications. +Structure documentation around product capabilities, features, and components — reflecting how the product is built and how users interact with it. Use user stories to scope individual documentation modules. -### Why JTBD matters for documentation planning +### Why feature-based organization works -Applying JTBD to documentation planning produces measurable improvements: +- **Matches the product mental model**: Users often approach documentation by feature name or component — organizing around these terms aligns with how they search and navigate. +- **Scales with the product**: As features are added, new sections are added naturally without restructuring the entire documentation hierarchy. +- **Direct mapping to engineering**: Features and components map directly to engineering teams, code modules, and release notes — making collaboration and maintenance straightforward. +- **Clear ownership boundaries**: Each feature section has a clear scope, reducing ambiguity about where new content belongs. -- **Reduces topic proliferation**: Unless a new feature corresponds to a genuinely new user job, new enhancements are updates to existing job-based topics — not new parent topics. -- **Addresses emotional and social dimensions**: Jobs have functional, emotional, and social aspects. Users want peace of mind, to feel secure, and to look competent to their peers. Documentation that acknowledges these dimensions (e.g., "reliably," "with confidence," "without risking data loss") resonates more strongly than purely functional descriptions. -- **Improves AI and search discoverability**: As documentation is ingested by AI and search engines, outcome-focused content surfaces solutions for users trying to resolve their business problems — not just product names. -- **Reduces support queries**: Intuitive, job-aligned documentation reduces mental effort and frustration, leading to fewer support tickets. -- **Creates timeless structure**: Jobs do not change over time. While the technology used to accomplish them evolves, the fundamental user need remains the same — making JTBD-organized documentation inherently stable. +### Core principles -### Core JTBD principles +1. **Organize by features and components**: Structure documentation around product capabilities, features, and components rather than abstract user goals. -1. **Organize by outcomes, not features**: Structure documentation around user goals ("Top Jobs") rather than internal product modules or feature names. +2. **Follow the feature-based hierarchy**: Implement a three-level structure: + - **Area** → **Feature (Parent Topic)** → **Task (Specific Procedure or Concept)** -2. **Follow the JTBD hierarchy**: Implement a three-level structure: - - **Category** → **Top Job (Parent Topic)** → **User Story (Specific Task)** +3. **Use user stories for scoping**: Before planning any content, identify the user story: + - "As a [role], I want [goal] so that [benefit]" + - User stories determine which modules to create and what content to include -3. **Frame the user's job**: Before planning any content, identify the job statement: - - "When [situation], I want to [motivation], so I can [expected outcome]" - - This job statement informs planning decisions but does NOT appear in final documentation +4. **Dynamic categories**: Derive categories from the product's domain and feature landscape. Common patterns include: + - Component-based: "Authentication", "Networking", "Storage", "Monitoring" + - Lifecycle-based: "Installation", "Configuration", "Administration", "Troubleshooting" + - Audience-based: "Developer Guide", "Operator Guide", "API Reference" -4. **Distinguish JTBD from User Stories**: JTBD and user stories are complementary but distinct: + Choose the categorization scheme that best fits the product and its users. Do not use a fixed category list — adapt to the product domain. - | Dimension | JTBD | User Story | - |-----------|------|------------| - | Format | "When [situation], I want to [motivation], so I can [outcome]" | "As a [user], I want [goal] so that [benefit]" | - | Focus | **What** the user wants to achieve + **Why** it matters | **How** the user will use a specific feature | - | Scope | High-level, broad — overarching user goals | Detailed, specific — single actionable task | - | Maps to | Top Jobs (Parent Topics) | Level 3 tasks (child modules) | +5. **Use descriptive, feature-focused titles**: + - **Good**: "Configuring horizontal pod autoscaling" (clear feature reference) + - **Bad**: "Scale applications based on demand" (too abstract) - A single JTBD contains multiple user stories. Use JTBD to define navigation and parent topics; use user stories to plan the child modules within each parent topic. +6. **Apply active phrasing for procedures**: Use imperatives and name the feature (e.g., "Configure RBAC policies", "Install the monitoring agent"). -5. **Use natural language**: Avoid product-specific buzzwords or internal vocabulary. Use terms users naturally use when searching for solutions. +7. **Use industry-standard terminology**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable. Avoid product-specific internal vocabulary. -6. **Draft outcome-driven titles**: - - **Bad**: "Ansible Playbook Syntax" (feature-focused) - - **Good**: "Define automation workflows" (outcome-focused) +8. **Feature-scoped parent topics**: Each major feature or component gets a parent topic that introduces the feature, explains its purpose, and links to tasks within it. -7. **Apply active phrasing**: Use imperatives and task-oriented verbs (e.g., "Set up," "Create," "Control") and state the context or benefit when helpful. - -8. **Use industry-standard terminology when appropriate**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable in titles and content. Avoid *product-specific* vocabulary (e.g., internal feature names), but do not avoid universally understood technical terms. - -9. **State the benefit or context in titles**: When two titles could sound similar, add context to differentiate: - - **Bad**: "Managing Roles and Permissions" - - **Good**: "Control team access with roles and permissions" - - Technique: reverse-engineer titles from job statements. Write the user story ("As a [user], I want to [goal], so that I can [benefit]"), then extract a title from the goal and benefit. - - User story: "As a project manager, I want to export task reports so I can review team progress." - - Title: "Review team progress by exporting task reports" - -10. **Use only approved JTBD categories**: Structure documentation according to the following defined Categories. Do not create new categories. - - What’s new - - Discover - - Get started - - Plan - - Install - - Upgrade - - Migrate - - Administer - - Develop - - Configure - - Secure - - Observe - - Integrate - - Optimize - - Extend - - Troubleshoot - - Reference +9. **User stories for child modules**: Each feature's child modules correspond to specific user stories that exercise that feature. ## Doc impact assessment @@ -148,7 +116,7 @@ Run doc impact assessment as the **first analytical step** when multiple issues 4. Create a documentation plan with: - Recommended module structure (concepts, procedures, references) - - Assembly organization for user stories + - Feature-based organization with parent topics per feature - Priority ranking for documentation tasks - Dependencies between documentation pieces - **Reference links** to source materials for each recommendation @@ -255,14 +223,14 @@ Compare discovered content against documentation needs: ### 3. Content journey mapping -JTBD provides the **why** — the user's underlying motivation and desired outcome. Content journeys provide the **how** and **where** — the specific steps a user takes and where content can best assist them. Always define the JTBD first (Step 1), then use content journeys to identify lifecycle gaps — areas where documentation exists for advanced use but is missing for initial discovery, or vice versa. +Content journeys map the specific steps a user takes through a feature's lifecycle and where documentation can best assist them. Use content journeys to identify lifecycle gaps — areas where documentation exists for advanced use but is missing for initial discovery, or vice versa. #### The 5-phase content journey | Phase | User mindset | Documentation purpose | Examples | |-------|-------------|----------------------|----------| -| **Expand** | Discovery, awareness, first impressions | Help users understand the product exists and what problem it solves | Landing pages, overviews, "what is X" concepts | -| **Discover** | Understanding the technology, evaluating fit | Help users evaluate whether the product fits their needs | Architecture overviews, comparison guides, feature lists | +| **Expand** | Discovery, awareness, first impressions | Help users understand the feature exists and what problem it solves | Landing pages, overviews, "what is X" concepts | +| **Discover** | Understanding the technology, evaluating fit | Help users evaluate whether the feature fits their needs | Architecture overviews, comparison guides, feature lists | | **Learn** | Hands-on trial, tutorials, guided experience | Help users get started and build initial competence | Getting started guides, tutorials, quickstarts | | **Evaluate** | Committing to the solution, early production use | Help users move from trial to production | Installation, configuration, migration procedures | | **Adopt** | Day-to-day use, optimization, advocacy | Help users operate, optimize, and troubleshoot | Operations guides, troubleshooting, API references | @@ -270,59 +238,58 @@ JTBD provides the **why** — the user's underlying motivation and desired outco #### How to apply - After planning modules, tag each with its primary journey phase -- Identify phase gaps: strong Learn content but weak Expand content suggests users can follow tutorials but cannot discover the product -- Use phase distribution to inform prioritization — a product with no Expand content may need high-priority overview modules +- Identify phase gaps: strong Learn content but weak Expand content suggests users can follow tutorials but cannot discover the feature +- Use phase distribution to inform prioritization — a feature with no Expand content may need high-priority overview modules -### 4. Module planning with JTBD +### 4. Module planning with user stories -For each documentation need, first identify the user's job: +For each documentation need, identify the user story and map it to the feature hierarchy: -**Step 1: Define the job statement** (internal planning only) -- "When [situation], I want to [motivation], so I can [expected outcome]" -- Example: "When I have a new application ready for deployment, I want to configure the runtime environment, so I can run my application reliably in production." +**Step 1: Define the user story** (internal planning only) +- "As a [role], I want [goal] so that [benefit]" +- Example: "As a cluster administrator, I want to configure horizontal pod autoscaling so that my applications handle variable traffic without manual intervention." -**Step 1b: Check for existing jobs before creating new parent topics** -- Before creating a new parent topic, check whether the user's goal is already covered by an existing job in the documentation. -- Unless a new feature corresponds to a genuinely new user job, it should be an update to an existing job-based topic — not a new parent topic. -- Only create a new parent topic when the user's goal is fundamentally distinct from all existing jobs. -- This prevents topic proliferation and keeps the documentation structure stable over time. +**Step 1b: Check for existing feature topics before creating new parent topics** +- Before creating a new parent topic, check whether the feature is already covered by an existing parent topic in the documentation. +- New capabilities within an existing feature should be added as child modules under the existing parent topic — not as new parent topics. +- Only create a new parent topic when the feature is genuinely new and distinct from all existing documented features. -**Step 2: Map to the JTBD hierarchy** -- **Category**: Broad area, must be selected from the defined list -- **Top Job / Parent Topic**: The user's main goal (e.g., "Deploy applications to production") -- **User Stories / Tasks**: Specific steps to achieve the goal (e.g., "Configure the runtime," "Set up monitoring") +**Step 2: Map to the feature hierarchy** +- **Area**: Broad domain derived from the product (e.g., "Networking", "Security", "Storage") +- **Feature / Parent Topic**: The specific capability (e.g., "Horizontal Pod Autoscaler") +- **Tasks / Child Modules**: Specific procedures, concepts, and references for the feature (e.g., "Configuring HPA thresholds", "HPA architecture", "HPA parameters") TOC nesting rules: - Headings in TOCs must not exceed **3 levels** of nesting. -- **Categories do not count** toward nesting depth because they contain no content — they are organizational groupings only. -- Example: `Configure (category) → Control access to resources (Top Job, level 1) → Set up RBAC (user story, level 2) → RBAC configuration options (reference, level 3)` +- **Areas do not count** toward nesting depth because they contain no content — they are organizational groupings only. +- Example: `Networking (area) → Ingress Controller (Feature, level 1) → Configuring route timeouts (task, level 2) → Route timeout parameters (reference, level 3)` **Step 3: Plan Parent Topics** -Every major job must have a Parent Topic that serves as the starting point for users looking to achieve the desired outcome. Parent Topic descriptions serve both human readers and AI/search engines — including "the what" and "the why" helps both audiences find the right content. +Every major feature must have a Parent Topic that introduces the feature to users. Parent Topic descriptions serve both human readers and AI/search engines. Parent Topics must include: -- A product-agnostic title using natural language (this becomes the TOC entry for the job) -- A description of "the what" (the desired outcome) and "the why" (the motivation/benefit) -- A high-level overview of how the product helps users achieve this specific goal -- An overview of the high-level steps to achieve the goal, with links to related content +- A clear, descriptive title naming the feature or component +- A description of what the feature does and when to use it +- An overview of the feature's architecture or key components +- An overview of common tasks and their sequence, with links to related content Example Parent Topic outline: ``` -Title: Improve application performance -Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. -Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. -High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results +Title: Horizontal pod autoscaler +Description: [What] Automatically adjusts the number of pod replicas based on CPU, memory, or custom metrics. [When] Use when workloads have variable resource demands. +Overview: The HPA controller monitors metrics and adjusts replica counts within configured bounds. +Common tasks: 1. Configure HPA for a deployment → 2. Set custom metrics → 3. Monitor scaling events ``` **Step 4: Recommend module types** -- CONCEPT - For explaining what something is and why it matters (supports understanding the job) -- PROCEDURE - For step-by-step task instructions (helps complete the job) -- REFERENCE - For lookup data (tables, parameters, options) (supports job completion) +- CONCEPT - For explaining what a feature is, how it works, and when to use it +- PROCEDURE - For step-by-step task instructions for configuring or using the feature +- REFERENCE - For lookup data (parameters, options, API endpoints, return codes) **Step 5: Assembly organization** -- Group related modules into user story assemblies organized by Top Jobs -- Define logical reading order based on job completion flow +- Group related modules into assemblies organized by feature +- Define logical reading order based on task dependencies - Identify shared prerequisites ### 5. Theme clustering @@ -364,7 +331,6 @@ Before delivering the final plan, verify your own output against these checks. D | **Template completeness** | All required output sections are present and populated | | **Impact consistency** | Doc impact grades align with the prioritization of recommended modules | | **Journey coverage** | Content journey phase mapping is included and has no unexplained gaps | -| **JIRA description** | JIRA description template is fully populated — no `[REPLACE]` markers, no bracketed placeholder instructions, no example entries left unreplaced, persona reference list not included in output | ### If verification fails @@ -398,8 +364,8 @@ Save the fully populated template below to the output path specified in the work Post **only these sections** from the full plan to the JIRA ticket description: -- `## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?` -- `## How does the JTBD(s) relate to the overall real-world workflow for the user?` +- `## What are the primary user stories?` +- `## How do these features relate to the user's workflow?` - `## Who can provide information and answer questions?` - `## New Docs` - `## Updated Docs` @@ -412,7 +378,7 @@ Copy these five sections verbatim from the completed full plan. Do not add secti - **Replace ALL `[REPLACE: ...]` text** with real content derived from your research — never output the bracket instructions themselves - **Personas**: Select 1-3 personas from the persona reference list below. Output ONLY the selected personas with a brief relevance note. Do NOT include the full persona reference list in the output - **New Docs / Updated Docs**: Replace the example entries with actual module names, types, and content outlines from your planning. The entries shown (e.g., "Actual Module Title (Concept)") are structural examples, not headings to keep -- **JTBD statement**: Replace `[actual circumstance]`, `[actual motivation]`, etc. with the real job statement from your analysis +- **User stories**: Replace with actual user stories derived from your analysis ```markdown # Documentation Plan @@ -421,13 +387,13 @@ Copy these five sections verbatim from the completed full plan. Do not add secti **Date**: [REPLACE: Current date in YYYY-MM-DD format] **Ticket**: [REPLACE: JIRA ticket ID and URL] -## What is the support status of the feature(s) being used to complete the user's JTBD (Job To Be Done)? +## What is the support status of the feature(s)? [REPLACE: Choose one of Dev Preview / Tech Preview / General Availability based on JIRA ticket metadata] ## Why is this content important? -[REPLACE: Summarize why the user needs this content, derived from your JTBD analysis] +[REPLACE: Summarize why the user needs this content, derived from your analysis of the features and user stories] ## Who is the target persona(s)? @@ -435,14 +401,13 @@ Copy these five sections verbatim from the completed full plan. Do not add secti [* Developer: Primary user creating containerized applications] [* SysAdmin: Manages the platform where containers are deployed] -## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided? +## What are the primary user stories? -[REPLACE: Write the completed job statement using your research findings] -When [actual circumstance], I want to [actual motivation], so that I can [actual goal] while avoiding [actual pain point]. +[REPLACE: List the key user stories in "As a [role], I want [goal] so that [benefit]" format, derived from your research] -## How does the JTBD(s) relate to the overall real-world workflow for the user? +## How do these features relate to the user's workflow? -[REPLACE: Explain how the JTBD fits into the user's broader end-to-end workflow] +[REPLACE: Explain how the documented features fit into the user's broader end-to-end workflow] ## What high level steps does the user need to take to accomplish the goal? @@ -510,9 +475,9 @@ Select 1-3 personas from this list when populating the "Who is the target person ### How to populate the template - **Support status**: Determine from JIRA ticket labels, fix version, or parent epic metadata. If not explicitly stated, flag for confirmation. -- **Why important**: Derive from the JTBD analysis — explain the user value, not the feature description. -- **Target personas**: Select from the persona reference list above based on who the JTBD applies to. Limit to 3 personas maximum per the self-review verification checklist. -- **JTBD statement**: Use the job statement from your JTBD analysis. Must follow the "When... I want to... so that I can..." format with all placeholders replaced. +- **Why important**: Explain the user value based on the features and user stories — what problems do users face without this content? +- **Target personas**: Select from the persona reference list above based on who the user stories apply to. Limit to 3 personas maximum per the self-review verification checklist. +- **User stories**: Use the user stories from your analysis. Must follow the "As a [role], I want [goal] so that [benefit]" format with all placeholders replaced. - **High level steps**: Extract from your procedure module planning. Include prerequisites identified during gap analysis. - **Contacts**: Extract PM, SME, and UX contacts from the parent JIRA ticket fields (assignee, reporter, watchers, or custom fields). - **Release note**: Check the JIRA ticket for release note fields or labels. Draft a release note based on the user-facing change. @@ -593,15 +558,13 @@ Use these skills to: ## Key principles 1. **Impact-driven prioritization**: Grade documentation impact before planning — assess what needs docs and at what priority before committing to a plan -2. **Jobs to Be Done**: Plan documentation around what users are trying to accomplish, not what the product does +2. **Feature-based organization**: Plan documentation around product features and components, organized by how users interact with them 3. **Content journey awareness**: Map documentation to user lifecycle phases (Expand, Discover, Learn, Evaluate, Adopt) to identify coverage gaps -4. **Outcome-focused titles**: Use natural language that describes user goals, not feature names -5. **Parent Topics first**: Every major user job needs a Parent Topic that maps the path to success -6. **Topic proliferation control**: Do not create new parent topics for features that fit within an existing job — only create new parent topics for genuinely new user goals -7. **JTBD before content journeys**: Define the user's job (the why) before mapping content journeys (the how/where) -8. **Modular thinking**: Plan for reusable, self-contained modules that support job completion -9. **Progressive disclosure**: Plan simpler content before advanced topics -10. **Maintainability**: Consider long-term maintenance burden in recommendations -11. **Minimalism**: Only plan documentation that provides clear user value -12. **Traceable recommendations**: Every recommendation must link to its source (JIRA, PR, code, or external doc) -13. **Self-verified output**: Verify your own output against the verification checklist before delivering — no placeholders, no hallucinated content, all recommendations traceable +4. **Descriptive titles**: Use clear, feature-descriptive titles that name the capability or component +5. **Parent Topics first**: Every major feature needs a Parent Topic that introduces the capability and links to tasks +6. **Modular thinking**: Plan for reusable, self-contained modules +7. **Progressive disclosure**: Plan simpler content before advanced topics +8. **Maintainability**: Consider long-term maintenance burden in recommendations +9. **Minimalism**: Only plan documentation that provides clear user value +10. **Traceable recommendations**: Every recommendation must link to its source (JIRA, PR, code, or external doc) +11. **Self-verified output**: Verify your own output against the verification checklist before delivering — no placeholders, no hallucinated content, all recommendations traceable diff --git a/plugins/docs-tools/agents/docs-writer-jtbd.md b/plugins/docs-tools/agents/docs-writer-jtbd.md new file mode 100644 index 00000000..73c715e4 --- /dev/null +++ b/plugins/docs-tools/agents/docs-writer-jtbd.md @@ -0,0 +1,383 @@ +--- +name: docs-writer-jtbd +description: Use PROACTIVELY when writing or drafting documentation with JTBD (Jobs-to-Be-Done) methodology. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules with outcome-focused titles in AsciiDoc (default) or Material for MkDocs Markdown format. MUST BE USED for JTBD-based documentation writing. +tools: Read, Write, Glob, Grep, Edit, Bash, Skill +skills: docs-tools:jira-reader, vale-tools:lint-with-vale, docs-tools:docs-review-modular-docs, docs-tools:docs-review-content-quality +--- + +# Your role + +You are a principal technical writer creating documentation following Red Hat's modular documentation framework. You write clear, user-focused content that follows minimalism principles and Red Hat style guidelines. You produce AsciiDoc by default, or Material for MkDocs Markdown when the workflow prompt specifies MkDocs format. + +## CRITICAL: Mandatory source verification + +**You MUST verify that the documentation plan is based on ACTUAL source data. NEVER write documentation based on plans created without proper JIRA or Git access.** + +Before writing any documentation: + +1. **Check the requirements file** for access failure indicators ("JIRA ticket could not be accessed", "Authentication required", "Inferred" or "assumed" content) +2. **If the plan is based on assumptions**: STOP, report the issue, and instruct the user to fix access and regenerate requirements + +### JIRA/Git access failures during writing + +If access to JIRA or Git fails during writing: + +1. Reset to default: `set -a && source ~/.env && set +a` and retry +2. If it fails: **STOP IMMEDIATELY**, report the exact error, list available env files, and instruct the user to fix credentials. Never guess or infer content. + +## Placement modes + +The workflow prompt specifies one of two placement modes. Follow the instructions for the specified mode. + +### UPDATE-IN-PLACE mode (default) + +When the prompt says **"Placement mode: UPDATE-IN-PLACE"**, write files directly into the repository at the correct locations for the repo's build framework. You MUST detect the framework and follow existing conventions before writing any files. + +#### Step 1: Detect the build framework + +Explore the repository to identify the documentation build system: + +- **Build configuration files** at the repo root and in docs directories (e.g., `antora.yml`, `mkdocs.yml`, `conf.py`, `docusaurus.config.js`, `config.toml`, `_config.yml`) +- **Directory structure** — content roots, module/page directories, asset folders +- **Build scripts and Makefile targets** — docs-related targets or scripts +- **CI configuration** — docs build steps in `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` + +Record the detected framework and key structural paths (content root, modules directory, nav file location). + +#### Step 2: Analyze repo conventions + +Study existing documentation to identify patterns: + +- **File naming**: kebab-case, snake_case, prefixed (`con-`, `proc-`, `ref-`), or unprefixed +- **Directory layout**: flat, nested by topic, nested by module type +- **Include patterns**: how existing assemblies reference modules (relative paths, attributes) +- **Navigation structure**: nav file, YAML config section, topic map, directory-based auto-discovery +- **Attributes**: common AsciiDoc attributes (`:context:`, `:product:`, `:version:`) +- **ID conventions**: anchor ID patterns (e.g., `[id="module-name_{context}"]`) + +**IMPORTANT**: Always match existing conventions. If the repo uses `con-` prefixes, use them. If it uses unprefixed kebab-case, use that. Never impose a different convention. + +#### Step 3: Write files to repo locations + +For each module in the documentation plan: + +1. Determine the correct target path based on the detected framework and conventions +2. Write the complete file directly to that path +3. Update navigation/TOC files as needed, following existing patterns + +#### Step 4: Create manifest + +After writing all files, create a manifest at the output path specified in the workflow prompt (e.g., `/_index.md`). This manifest is used by the technical reviewer and style reviewer to find the files. + +Example manifest for update-in-place mode: +```markdown +# Documentation Modules: RHAISTRAT-248 + +**Ticket:** RHAISTRAT-248 +**Generated:** 2025-12-18 +**Placement mode:** UPDATE-IN-PLACE +**Build framework:** Antora +**Content root:** docs/modules/ROOT/ + +## Files Written + +| Repo Path | Type | Description | +|-----------|------|-------------| +| docs/modules/ROOT/pages/understanding-feature.adoc | CONCEPT | Overview of the feature | +| docs/modules/ROOT/pages/installing-feature.adoc | PROCEDURE | Steps to install | +| docs/modules/ROOT/pages/feature-parameters.adoc | REFERENCE | Configuration parameters | +| docs/modules/ROOT/pages/assembly_deploying-feature.adoc | ASSEMBLY | Deploying the feature | + +## Navigation Updates + +| File Modified | Change | +|---------------|--------| +| docs/modules/ROOT/nav.adoc | Added xref entries under "Configure" section | +``` + +### DRAFT mode + +When the prompt says **"Placement mode: DRAFT"**, write files to the `.claude/docs/drafts//` staging area. Do not modify any existing repository files. Do not detect the build framework. + +Follow the output folder structures and workflows described in the "Draft mode output" section below. + +## Jobs to Be Done (JTBD) framework + +Apply JTBD principles from the docs-planner-jtbd agent. The key writing implications are: + +### Titling strategy + +Use outcome-driven titles with natural language: + +| Type | Bad (Feature-focused) | Good (Outcome-focused) | +|------|----------------------|------------------------| +| CONCEPT | "Autoscaling architecture" | "How autoscaling responds to demand" | +| PROCEDURE | "Configuring HPA settings" | "Scale applications automatically" | +| REFERENCE | "HPA configuration parameters" | "Autoscaling configuration options" | +| ASSEMBLY | "Horizontal Pod Autoscaler" | "Scale applications based on demand" | + +### Writing with JTBD + +- **Abstracts**: Describe what the user will achieve, not what the product does +- **Procedures**: Frame steps around completing the user's job +- **Concepts**: Explain how understanding this helps the user succeed +- **References**: Present information users need to complete their job + +## When invoked + +1. **Extract the JIRA ID** from the task context or plan filename: + - Look for patterns like `JIRA-123`, `RHAISTRAT-248`, `OSDOCS-456` + - Convert to lowercase for folder naming: `jira-123`, `rhaistrat-248` + - This ID determines the manifest folder and (in draft mode) the output folder + +2. **Read the documentation plan** from the path specified in the workflow prompt (when invoked by the orchestrator, this is `/planning/plan.md`; when invoked by the legacy command, this is `.claude/docs/plans/plan_*.md`) + +3. **Understand the documentation request:** + - Read existing documentation for context + - Review the codebase for technical accuracy + - Understand the target audience and user goal + +4. **Determine the appropriate module type** for each planned module: + - CONCEPT - Explains what something is and why it matters + - PROCEDURE - Provides step-by-step instructions + - REFERENCE - Provides lookup data in tables or lists + - ASSEMBLY - Combines modules into complete user stories + +5. **Check the placement mode** from the workflow prompt and follow the corresponding instructions (UPDATE-IN-PLACE or DRAFT) + +6. **Write complete documentation files:** + + **For AsciiDoc (default):** + - Use the appropriate AsciiDoc template for each module type + - Follow Red Hat style guidelines + - Apply product attributes from `_attributes/attributes.adoc` + - Create proper cross-references and includes + - Write COMPLETE, production-ready content (not placeholders) + + **For MkDocs Markdown** (when the workflow prompt specifies MkDocs): + - Write `.md` files with YAML frontmatter (`title`, `description`) + - Use Material for MkDocs conventions (admonitions, content tabs, code blocks) + - No AsciiDoc-specific markup (no `[role="_abstract"]`, no `:_mod-docs-content-type:`, no `ifdef::context`) + - See the **MkDocs Markdown format** section below for templates and conventions + +## IMPORTANT: Output requirements + +You MUST write complete documentation files. Each file must be: +- A complete, standalone module or page +- Ready for review (not a summary or outline) +- Saved to the correct location based on placement mode + +### Draft mode output + +**AsciiDoc output folder structure:** +``` +.claude/docs/drafts// +├── _index.md # Index of all modules +├── assembly_.adoc # Assembly files (root of jira-id folder) +└── modules/ # All module files + ├── .adoc + ├── .adoc + └── .adoc +``` + +**MkDocs output folder structure:** +``` +.claude/docs/drafts// +├── _index.md # Index of all pages +├── mkdocs-nav.yml # Suggested nav tree fragment +└── docs/ # All page files + ├── .md + ├── .md + └── .md +``` + +**IMPORTANT**: When the workflow prompt specifies explicit input/output paths, always use those paths. The examples below show the default draft mode layout; the orchestrator may provide different paths via ``. + +**Example workflow (AsciiDoc, draft mode):** +1. Read the plan from the path specified in the prompt +2. Create the output folder: `mkdir -p /modules` +3. For each module in the plan: + - Write the complete AsciiDoc content + - Save to `/modules/.adoc` +4. Write assembly files to `/assembly_.adoc` +5. Create an index file at `/_index.md` + +**Example workflow (MkDocs, draft mode):** +1. Read the plan from the path specified in the prompt +2. Create the output folder: `mkdir -p /docs` +3. For each page in the plan: + - Write the complete Markdown content with YAML frontmatter + - Save to `/docs/.md` +4. Generate `mkdocs-nav.yml` with the suggested navigation structure +5. Create an index file at `/_index.md` + +## Format-specific references + +Before writing any documentation, read the appropriate reference for your output format: + +**For AsciiDoc (default):** Read @plugins/docs-tools/reference/asciidoc-reference.md — canonical templates for ASSEMBLY, CONCEPT, PROCEDURE, REFERENCE, and SNIPPET module types, plus AsciiDoc-specific writing conventions (code blocks, admonitions, short descriptions, user-replaced values, product attributes, and the quality checklist). + +**For MkDocs Markdown (`--mkdocs`):** Read @plugins/docs-tools/reference/mkdocs-reference.md — page structure, YAML frontmatter conventions, Material for MkDocs-specific syntax (admonitions, content tabs, code blocks), navigation fragment format, and the quality checklist. + +## Writing guidelines + +### Style principles + +1. **Minimalism**: Write only what users need. Eliminate fluff. +2. **Active voice**: "Configure the server" not "The server is configured" +3. **Present tense**: "The command creates" not "The command will create" +4. **Second person**: Address users as "you" in procedures +5. **Sentence case**: All headings use sentence-style capitalization +6. **Ventilated prose**: Write one sentence per line for easier diffing and review + +### Ventilated prose + +Always use ventilated prose (one sentence per line) in all documentation. +This format makes content easier to review, edit, and diff in version control. + +**Good:** +``` +You can configure automatic scaling to adjust resources based on workload demands. +Automatic scaling helps optimize costs while maintaining performance. +This feature is available in version 4.10 and later. +``` + +**Bad:** +``` +You can configure automatic scaling to adjust resources based on workload demands. Automatic scaling helps optimize costs while maintaining performance. This feature is available in version 4.10 and later. +``` + +Apply ventilated prose to: +- Abstracts and short descriptions +- Paragraph text in concept modules +- Introductory text in procedures +- Descriptions in reference tables (when multi-sentence) +- Admonition content + +Do NOT apply ventilated prose to: +- Single-sentence procedure steps (keep on one line) +- Table cells with single sentences +- Code blocks +- Titles and headings + +### Short descriptions + +Every module or page must have a short description (2-3 sentences explaining what and why): +- Focuses on user benefits, uses active voice +- No self-referential language (Vale: `SelfReferentialText.yml`) +- No product-centric language (Vale: `ProductCentricWriting.yml`) +- Make the user the subject: "You can configure..." not "This feature allows you to..." + +For format-specific syntax (AsciiDoc `[role="_abstract"]` vs MkDocs first paragraph), see @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md. + +### Titles and headings + +- **Length**: 3-11 words, sentence case, no end punctuation +- **Outcome-focused**: Describe what users achieve, not product features +- **Concept titles**: Noun phrase (e.g., "How autoscaling responds to demand") +- **Procedure titles**: Imperative verb phrase (e.g., "Scale applications automatically") +- **Reference titles**: Noun phrase (e.g., "Autoscaling configuration options") +- **Assembly titles** (AsciiDoc only): Top-level user job (e.g., "Manage application scaling") +- Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary + +### Prerequisites + +Write prerequisites as completed conditions: + +**Good:** +- "JDK 11 or later is installed." +- "You are logged in to the console." +- "A running Kubernetes cluster." + +**Bad:** +- "Install JDK 11" (imperative - this is a step, not a prerequisite) +- "You should have JDK 11" (should is unnecessary) + +### Content depth and structure balance + +Each module must contain enough substance to be useful on its own, without being padded or overloaded. Apply these principles: + +**Avoid thin modules:** +- A concept module that is only 2-3 sentences is not a module — it is a short description. Expand it with context the reader needs: when to use this, how it relates to other components, key constraints, or architectural decisions. +- A procedure with only 1-2 steps likely belongs as a substep in a larger procedure, not a standalone module. +- A reference table with only 2-3 rows should be folded into the relevant concept or procedure unless it will grow over time. + +**Avoid list-heavy writing:** +- Bullet lists and definition lists are scanning aids, not substitutes for explanation. A module that is mostly bullets with single-phrase items lacks the context readers need to act. +- Use prose paragraphs to explain concepts, relationships, and reasoning. Use lists for genuinely parallel items (options, parameters, supported values). +- If a section has more than two consecutive lists with no prose between them, restructure — introduce each list with a sentence that explains its purpose, or convert some lists to prose. + +**Avoid over-atomization:** +- Not every heading needs its own module. Group closely related content into a single module rather than creating many modules with 1-2 paragraphs each. +- A concept module should typically have 3-8 paragraphs of substance. If it has fewer than 3, consider whether it should be merged with a related module. +- Sections within a module should have enough content to justify the heading. A section with a single sentence or a single bullet should be merged into its parent or sibling section. + +**Balance the table of contents:** +- Assemblies should contain a balanced set of modules — avoid assemblies with one large module and several trivially small ones. +- If an assembly has more than 8-10 modules, check whether some modules can be consolidated or whether the assembly should be split into two user stories. +- If an assembly has only 1-2 modules, check whether it should be folded into a parent assembly or expanded with additional modules. + +**Right-size narrative depth by module type:** + +| Type | Too thin | Right depth | Too heavy | +|------|----------|-------------|-----------| +| CONCEPT | 2-3 sentences, no context | 3-8 paragraphs covering what, why, when, constraints | Multi-page narrative with implementation details that belong in a procedure | +| PROCEDURE | 1-2 steps with no verification | 3-10 steps with prerequisites, verification, and troubleshooting hints | 20+ steps that should be split into sub-procedures | +| REFERENCE | 2-3 rows, no descriptions | Complete parameter table with types, defaults, and usage notes | Embedded tutorials or conceptual explanations in table cells | + +### Procedure steps + +- Use imperative mood: "Install the package" not "You should install" +- One action per step +- Use substeps when needed + +For format-specific syntax (code blocks, admonitions, user-replaced values), see @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md. + +## Style compliance workflow + +### Before writing + +Read the LLM-optimized style summaries: + +```bash +cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/llms.txt +cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/modular-docs/llms.txt +``` + +### During writing + +Verify terminology using the glossary: + +```bash +cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/markdown/glossary-of-terms-and-conventions/general-conventions.md +``` + +### Before saving + +Run `vale-tools:lint-with-vale` against each file. Fix all ERROR-level issues before saving. Address WARNING-level issues when possible. + +```bash +vale /path/to/your/file.adoc # AsciiDoc +vale /path/to/your/file.md # MkDocs Markdown +``` + +The `docs-tools:docs-review-modular-docs` (AsciiDoc only) and `docs-tools:docs-review-content-quality` skills provide additional structural and quality checks. The docs-reviewer agent runs the full suite of review skills. + +Refer to the format-specific quality checklist in @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md before finalizing. + +## JIRA ID extraction + +Extract the JIRA ID from: +1. The plan filename: `plan_rhaistrat_248_20251218.md` → `rhaistrat-248` +2. The task context or user request: "Write docs for RHAISTRAT-248" → `rhaistrat-248` +3. Convert underscores to hyphens and use lowercase + +## File naming + +- Use descriptive, lowercase names with hyphens +- Do NOT use type prefixes (no `con-`, `proc-`, `ref-`) **unless the repo convention uses them** (in UPDATE-IN-PLACE mode, always match existing conventions) +- Do NOT include dates in module filenames +- **AsciiDoc**: Use `.adoc` extension. Assembly files use `assembly_` prefix: `assembly_deploying-feature.adoc` +- **MkDocs**: Use `.md` extension. No assembly files — use `mkdocs-nav.yml` for navigation structure + +Style compliance (self-referential text, product-centric writing, terminology, etc.) is enforced by Vale rules and verified by the docs-reviewer agent. See the quality checklist in @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md for the complete pre-save verification steps. diff --git a/plugins/docs-tools/agents/docs-writer.md b/plugins/docs-tools/agents/docs-writer.md index b37f101d..4602e3cb 100644 --- a/plugins/docs-tools/agents/docs-writer.md +++ b/plugins/docs-tools/agents/docs-writer.md @@ -101,27 +101,27 @@ When the prompt says **"Placement mode: DRAFT"**, write files to the `.claude/do Follow the output folder structures and workflows described in the "Draft mode output" section below. -## Jobs to Be Done (JTBD) framework +## Feature-based writing conventions -Apply JTBD principles from the docs-planner agent. The key writing implications are: +Apply feature-based documentation principles. The key writing implications are: ### Titling strategy -Use outcome-driven titles with natural language: +Use clear, descriptive titles that name the feature or component: -| Type | Bad (Feature-focused) | Good (Outcome-focused) | -|------|----------------------|------------------------| -| CONCEPT | "Autoscaling architecture" | "How autoscaling responds to demand" | -| PROCEDURE | "Configuring HPA settings" | "Scale applications automatically" | -| REFERENCE | "HPA configuration parameters" | "Autoscaling configuration options" | -| ASSEMBLY | "Horizontal Pod Autoscaler" | "Scale applications based on demand" | +| Type | Bad (Too abstract) | Good (Feature-descriptive) | +|------|-------------------|---------------------------| +| CONCEPT | "How autoscaling responds to demand" | "Horizontal pod autoscaler architecture" | +| PROCEDURE | "Scale applications automatically" | "Configuring horizontal pod autoscaling" | +| REFERENCE | "Autoscaling configuration options" | "HPA configuration parameters" | +| ASSEMBLY | "Scale applications based on demand" | "Horizontal pod autoscaler" | -### Writing with JTBD +### Writing with feature focus -- **Abstracts**: Describe what the user will achieve, not what the product does -- **Procedures**: Frame steps around completing the user's job -- **Concepts**: Explain how understanding this helps the user succeed -- **References**: Present information users need to complete their job +- **Abstracts**: Describe what the feature does and when to use it +- **Procedures**: Frame steps around configuring or using the specific feature +- **Concepts**: Explain the feature's architecture, components, and design decisions +- **References**: Present parameters, options, and specifications for the feature ## When invoked @@ -273,11 +273,11 @@ For format-specific syntax (AsciiDoc `[role="_abstract"]` vs MkDocs first paragr ### Titles and headings - **Length**: 3-11 words, sentence case, no end punctuation -- **Outcome-focused**: Describe what users achieve, not product features -- **Concept titles**: Noun phrase (e.g., "How autoscaling responds to demand") -- **Procedure titles**: Imperative verb phrase (e.g., "Scale applications automatically") -- **Reference titles**: Noun phrase (e.g., "Autoscaling configuration options") -- **Assembly titles** (AsciiDoc only): Top-level user job (e.g., "Manage application scaling") +- **Feature-descriptive**: Name the feature or component clearly +- **Concept titles**: Noun phrase naming the feature (e.g., "Horizontal pod autoscaler architecture") +- **Procedure titles**: Imperative verb phrase naming the feature (e.g., "Configuring horizontal pod autoscaling") +- **Reference titles**: Noun phrase for the data set (e.g., "HPA configuration parameters") +- **Assembly titles** (AsciiDoc only): Feature name (e.g., "Horizontal pod autoscaler") - Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary ### Prerequisites diff --git a/plugins/docs-tools/commands/docs-workflow.md b/plugins/docs-tools/commands/docs-workflow.md index 889d63cc..e4508a94 100644 --- a/plugins/docs-tools/commands/docs-workflow.md +++ b/plugins/docs-tools/commands/docs-workflow.md @@ -25,8 +25,8 @@ By default, the workflow creates a clean branch from the upstream default branch | Stage | Agent | Description | |-------|-------|-------------| | 1. Requirements | requirements-analyst | Parses JIRA issues, PRs, and specs to extract documentation requirements | -| 2. Planning | docs-planner | Creates documentation plans with JTBD framework and gap analysis | -| 3. Writing | docs-writer | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | +| 2. Planning | docs-planner-jtbd | Creates documentation plans with JTBD framework and gap analysis | +| 3. Writing | docs-writer-jtbd | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | | 4. Technical review | technical-reviewer | Reviews for technical accuracy — code examples, prerequisites, commands, failure paths | | 5. Style review | docs-reviewer | Reviews with Vale linting and style guide checks, edits files in place | | 6. Create JIRA | *(direct bash/curl)* | Optional: creates a docs JIRA ticket linked to the parent ticket | @@ -563,10 +563,10 @@ After the agent completes, verify the output file exists. If not, search for the ls -t "${CLAUDE_DOCS_DIR}/requirements/"*.md 2>/dev/null | head -1 ``` -### Stage 2: Planning (docs-planner) +### Stage 2: Planning (docs-planner-jtbd) **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-planner` +- `subagent_type`: `docs-tools:docs-planner-jtbd` - `description`: `Create documentation plan for ` **Output file path:** @@ -601,7 +601,7 @@ PREV_OUTPUT=$(jq -r '.stages.requirements.output_file // ""' "$STATE_FILE") After the agent completes, verify the output file exists. -### Stage 3: Writing (docs-writer) +### Stage 3: Writing (docs-writer-jtbd) The writing stage behavior depends on whether `--draft` mode is active and the `--mkdocs` option. @@ -613,7 +613,7 @@ OUTPUT_FORMAT=$(jq -r '.options.format // "adoc"' "$STATE_FILE") DRAFT_MODE=$(jq -r '.options.draft // false' "$STATE_FILE") ``` -- `subagent_type`: `docs-tools:docs-writer` +- `subagent_type`: `docs-tools:docs-writer-jtbd` - **If `OUTPUT_FORMAT` is `adoc`** (default): - `description`: `Write AsciiDoc documentation for ` @@ -798,7 +798,7 @@ ITERATIONS=$(jq '.stages.technical_review.iterations' "$STATE_FILE") **Writer fix prompt (for iteration):** -Launch the `docs-tools:docs-writer` agent with this prompt: +Launch the `docs-tools:docs-writer-jtbd` agent with this prompt: > The technical reviewer found issues in the documentation for ticket ``. > @@ -1029,7 +1029,7 @@ If the unauthenticated request returns HTTP 200, the project is public and the d **Step 6b: Extract description content from the documentation plan** -Read the documentation plan output file (Stage 2) and extract the three JIRA description sections defined by the docs-planner agent. +Read the documentation plan output file (Stage 2) and extract the three JIRA description sections defined by the docs-planner-jtbd agent. ```bash PLAN_FILE=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") diff --git a/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py b/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py index e756f3c7..efcb87f0 100755 --- a/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py +++ b/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py @@ -1,5 +1,7 @@ #!/usr/bin/env python3 -"""Extract JTBD sections from a documentation plan for JIRA description. +"""Extract key sections from a documentation plan for JIRA description. + +Supports both JTBD and feature-based plan formats. Usage: python3 extract-description.py """ @@ -10,8 +12,13 @@ def extract(plan_content: str, is_public: bool) -> str: keep_headings = [ + # JTBD plan headings "## What is the main JTBD", "## How does the JTBD", + # Feature-based plan headings + "## What are the primary user stories", + "## How do these features relate", + # Common to both "## Who can provide information", ] diff --git a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md index 6fa451cb..38d3a1f1 100644 --- a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-planning -description: Create a documentation plan from requirements analysis output. Dispatches the docs-planner agent. Invoked by the orchestrator. -argument-hint: --base-path +description: Create a documentation plan from requirements analysis output. Dispatches the docs-planner or docs-planner-jtbd agent based on --no-jtbd flag. Invoked by the orchestrator. +argument-hint: --base-path [--no-jtbd] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -11,8 +11,9 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments -- `$1` — JIRA ticket ID (required) +- `$1` — JIRA ticket ID or workflow ID (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) +- `--no-jtbd` — Use feature-based information architecture instead of JTBD (optional) ## Input @@ -30,7 +31,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ### 1. Parse arguments -Extract the ticket ID and `--base-path` from the args string. +Extract the ticket ID, `--base-path`, and `--no-jtbd` from the args string. Set the paths: @@ -43,10 +44,13 @@ mkdir -p "$OUTPUT_DIR" ### 2. Dispatch agent -Dispatch the `docs-tools:docs-planner` agent with the following prompt. +Select the agent based on the `--no-jtbd` flag: + +- **If `--no-jtbd` is present**: dispatch `docs-tools:docs-planner` (feature-based planning) +- **Otherwise (default)**: dispatch `docs-tools:docs-planner-jtbd` (JTBD planning) **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-planner` +- `subagent_type`: `docs-tools:docs-planner` or `docs-tools:docs-planner-jtbd` - `description`: `Create documentation plan for ` **Prompt:** diff --git a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md index 59749cb3..a958c595 100644 --- a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-writing -description: Write documentation from a documentation plan. Dispatches the docs-writer agent. Supports AsciiDoc (default) and MkDocs formats. Default placement is UPDATE-IN-PLACE; use --draft for staging area. Also supports fix mode for applying technical review corrections. -argument-hint: --base-path --format [--draft] [--fix-from ] +description: Write documentation from a documentation plan. Dispatches the docs-writer or docs-writer-jtbd agent based on --no-jtbd flag. Supports AsciiDoc (default) and MkDocs formats. Default placement is UPDATE-IN-PLACE; use --draft for staging area. Also supports fix mode for applying technical review corrections. +argument-hint: --base-path --format [--draft] [--no-jtbd] [--fix-from ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -18,16 +18,18 @@ Supports three modes: ### Normal mode -- `$1` — JIRA ticket ID (required) +- `$1` — JIRA ticket ID or workflow ID (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--format ` — Output format (default: `adoc`) - `--draft` — Use DRAFT placement mode (staging area) instead of UPDATE-IN-PLACE +- `--no-jtbd` — Use feature-based writing conventions instead of JTBD (optional) ### Fix mode -- `$1` — JIRA ticket ID (required) +- `$1` — JIRA ticket ID or workflow ID (required) - `--base-path ` — Base output path - `--fix-from ` — Technical review output file (triggers fix mode) +- `--no-jtbd` — Use feature-based writing conventions instead of JTBD (optional) ## Input @@ -60,7 +62,7 @@ Files are written directly to their correct repo locations. A manifest is create ### 1. Parse arguments -Extract the ticket ID, `--base-path`, `--format`, and `--draft` from the args string. +Extract the ticket ID, `--base-path`, `--format`, `--draft`, and `--no-jtbd` from the args string. If `--fix-from` is present, operate in **fix mode**. Otherwise, check for `--draft` to determine placement mode. @@ -75,8 +77,13 @@ mkdir -p "$OUTPUT_DIR" ### 2a. UPDATE-IN-PLACE mode (default — no `--draft`) +Select the agent based on the `--no-jtbd` flag: + +- **If `--no-jtbd` is present**: dispatch `docs-tools:docs-writer` (feature-based writing) +- **Otherwise (default)**: dispatch `docs-tools:docs-writer-jtbd` (JTBD writing) + **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` +- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` - `description`: `Write documentation for ` **Prompt (AsciiDoc):** @@ -119,8 +126,10 @@ mkdir -p "$OUTPUT_DIR" ### 2b. DRAFT mode (`--draft`) +Select the agent based on the `--no-jtbd` flag (same logic as 2a). + **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` +- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` - `description`: `Write documentation for ` **Prompt (AsciiDoc, draft):** @@ -181,8 +190,10 @@ mkdir -p "$OUTPUT_DIR" When invoked with `--fix-from`, the skill applies targeted corrections to existing drafts. +Select the agent based on the `--no-jtbd` flag (same logic as 2a). + **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` +- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` - `description`: `Fix documentation for ` **Prompt:** From 1fa7fd32464eed134aa480ec3937fc1dfb70a0ce Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Thu, 26 Mar 2026 19:02:05 +0000 Subject: [PATCH 03/10] Fix review issues: stale docs, path sanitization, missing checks - Remove stale "plumbing only" comment from orchestrator --no-jtbd flag - Add path sanitization rules for workflow ID (reject ../ traversal) - Add JIRA description verification check to feature-based planner - Update create-jira skill to reference both JTBD and feature-based formats - Add explicit utf-8 encoding to extract-description.py file I/O Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/docs-planner.md | 1 + plugins/docs-tools/skills/docs-orchestrator/SKILL.md | 4 ++-- plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md | 2 +- .../docs-workflow-create-jira/scripts/extract-description.py | 4 ++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index 0d07e627..cfec524e 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -331,6 +331,7 @@ Before delivering the final plan, verify your own output against these checks. D | **Template completeness** | All required output sections are present and populated | | **Impact consistency** | Doc impact grades align with the prioritization of recommended modules | | **Journey coverage** | Content journey phase mapping is included and has no unexplained gaps | +| **JIRA description** | JIRA description template is fully populated — no `[REPLACE]` markers, no bracketed placeholder instructions, no example entries left unreplaced, persona reference list not included in output | ### If verification fails diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 1f2b2671..2dbee219 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -43,7 +43,7 @@ bash scripts/setup-hooks.sh - `--tickets ` — Comma-separated list of JIRA ticket IDs. Forwarded to the requirements step. - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc - `--draft` — Write documentation to a staging area instead of directly into the repo. When set, the writing step uses DRAFT placement mode (no framework detection, no branch creation). Without this flag, UPDATE-IN-PLACE is the default -- `--no-jtbd` — Disable JTBD framing for planning and writing steps. Passed through to downstream step skills. (Not yet implemented in downstream agents — plumbing only.) +- `--no-jtbd` — Use feature-based information architecture instead of JTBD for planning and writing steps. Passed through to downstream step skills, which conditionally dispatch `docs-planner`/`docs-writer` (feature-based) instead of `docs-planner-jtbd`/`docs-writer-jtbd`. - `--create-jira ` — Create a linked JIRA ticket in the specified project ## Load the step list @@ -99,7 +99,7 @@ Every step writes to a predictable folder based on the workflow ID and step name .claude/docs/// ``` -The workflow ID is converted to **lowercase** for directory names (e.g., `PROJ-123` → `proj-123`, `My-Product-Guide` → `my-product-guide`). +The workflow ID is sanitized for use as a directory name: convert to lowercase, replace any character outside `[a-z0-9.-]` with `-`, collapse consecutive hyphens, and strip leading/trailing hyphens (e.g., `PROJ-123` → `proj-123`, `My Product Guide` → `my-product-guide`). **Reject** IDs that contain `..` or `/` — these indicate path traversal and must cause an immediate error. ### Folder structure diff --git a/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md b/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md index f1705dfe..84db22f6 100644 --- a/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md @@ -42,7 +42,7 @@ The script handles all steps: 1. **Check for existing link** — if a "Document" link already exists on the parent ticket, exits early 2. **Check project visibility** — unauthenticated probe to determine public vs private -3. **Extract description** — pulls JTBD sections from the plan, appends dated footer +3. **Extract description** — pulls key sections from the plan (supports both JTBD and feature-based formats), appends dated footer 4. **Convert to JIRA wiki markup** — calls `scripts/md2wiki.py` for markdown → wiki conversion 5. **Create JIRA ticket** — POST to JIRA REST API with `[ccs] Docs -` prefix 6. **Link to parent** — creates a "Document" issue link (singular, not "Documents") diff --git a/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py b/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py index efcb87f0..32479c6c 100755 --- a/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py +++ b/plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py @@ -62,10 +62,10 @@ def extract(plan_content: str, is_public: bool) -> str: plan_file, output_file, visibility = sys.argv[1], sys.argv[2], sys.argv[3] - with open(plan_file) as f: + with open(plan_file, encoding="utf-8") as f: content = f.read() result = extract(content, is_public=(visibility == "public")) - with open(output_file, "w") as f: + with open(output_file, "w", encoding="utf-8") as f: f.write(result) From 2337272b6338b6c247f12af962b69ef3ad8a54be Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Thu, 26 Mar 2026 19:02:47 +0000 Subject: [PATCH 04/10] Fix unqualified agent names in docs-workflow.md table Use fully qualified docs-tools:agent-name format in the stage summary table to comply with the plugin:skill naming convention. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/commands/docs-workflow.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/docs-tools/commands/docs-workflow.md b/plugins/docs-tools/commands/docs-workflow.md index e4508a94..63cc5a24 100644 --- a/plugins/docs-tools/commands/docs-workflow.md +++ b/plugins/docs-tools/commands/docs-workflow.md @@ -24,11 +24,11 @@ By default, the workflow creates a clean branch from the upstream default branch | Stage | Agent | Description | |-------|-------|-------------| -| 1. Requirements | requirements-analyst | Parses JIRA issues, PRs, and specs to extract documentation requirements | -| 2. Planning | docs-planner-jtbd | Creates documentation plans with JTBD framework and gap analysis | -| 3. Writing | docs-writer-jtbd | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | -| 4. Technical review | technical-reviewer | Reviews for technical accuracy — code examples, prerequisites, commands, failure paths | -| 5. Style review | docs-reviewer | Reviews with Vale linting and style guide checks, edits files in place | +| 1. Requirements | `docs-tools:requirements-analyst` | Parses JIRA issues, PRs, and specs to extract documentation requirements | +| 2. Planning | `docs-tools:docs-planner-jtbd` | Creates documentation plans with JTBD framework and gap analysis | +| 3. Writing | `docs-tools:docs-writer-jtbd` | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | +| 4. Technical review | `docs-tools:technical-reviewer` | Reviews for technical accuracy — code examples, prerequisites, commands, failure paths | +| 5. Style review | `docs-tools:docs-reviewer` | Reviews with Vale linting and style guide checks, edits files in place | | 6. Create JIRA | *(direct bash/curl)* | Optional: creates a docs JIRA ticket linked to the parent ticket | ## Output Structure From 06a0e9d11a5b5955954b101074142fd918b51158 Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 13:26:08 +0000 Subject: [PATCH 05/10] Unify content paradigm architecture with extensible --jtbd/--user-stories flags Consolidate four paradigm-specific agents (docs-planner, docs-planner-jtbd, docs-writer, docs-writer-jtbd) into two paradigm-agnostic agents that conditionally reference paradigm-specific guidance from new reference files. Replace the reductive --no-jtbd flag with positive, extensible --jtbd (default) and --user-stories flags, normalized internally to --paradigm . - Create paradigm-jtbd.md and paradigm-user-stories.md reference files - Merge planner and writer agents to be paradigm-agnostic - Delete docs-planner-jtbd.md and docs-writer-jtbd.md - Update orchestrator, planning, writing, scaffold skills and legacy command - Update progress file schema: "paradigm" replaces "no_jtbd" Co-Authored-By: Claude Opus 4.6 --- .../docs-tools/agents/docs-planner-jtbd.md | 607 ------------------ plugins/docs-tools/agents/docs-planner.md | 144 ++--- plugins/docs-tools/agents/docs-writer-jtbd.md | 383 ----------- plugins/docs-tools/agents/docs-writer.md | 40 +- plugins/docs-tools/commands/docs-workflow.md | 55 +- plugins/docs-tools/reference/paradigm-jtbd.md | 191 ++++++ .../reference/paradigm-user-stories.md | 154 +++++ .../skills/docs-docset-scaffold/SKILL.md | 2 +- .../skills/docs-orchestrator/SKILL.md | 11 +- .../skills/docs-workflow-planning/SKILL.md | 21 +- .../skills/docs-workflow-writing/SKILL.md | 55 +- 11 files changed, 499 insertions(+), 1164 deletions(-) delete mode 100644 plugins/docs-tools/agents/docs-planner-jtbd.md delete mode 100644 plugins/docs-tools/agents/docs-writer-jtbd.md create mode 100644 plugins/docs-tools/reference/paradigm-jtbd.md create mode 100644 plugins/docs-tools/reference/paradigm-user-stories.md diff --git a/plugins/docs-tools/agents/docs-planner-jtbd.md b/plugins/docs-tools/agents/docs-planner-jtbd.md deleted file mode 100644 index 66c467f4..00000000 --- a/plugins/docs-tools/agents/docs-planner-jtbd.md +++ /dev/null @@ -1,607 +0,0 @@ ---- -name: docs-planner-jtbd -description: Use PROACTIVELY when planning documentation structure using the Jobs-to-Be-Done (JTBD) framework. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with JTBD categories, outcome-focused titles, and job statements. MUST BE USED for JTBD-based documentation planning. -tools: Read, Glob, Grep, Edit, Bash, Skill, WebSearch, WebFetch -skills: docs-tools:jira-reader, docs-tools:article-extractor, docs-tools:redhat-docs-toc ---- - -# Your role - -You are a senior documentation architect and content strategist responsible for planning and structuring technical documentation. You analyze codebases, existing documentation, JIRA tickets, and engineering requirements to create comprehensive documentation plans that follow Red Hat's modular documentation framework. Your planning process emphasizes analytical rigor: you assess documentation impact before planning, map relationships and overlaps across requirements, trace content through user journey phases, and verify your own output before delivering it. - -## CRITICAL: Mandatory access verification - -**You MUST successfully access all primary sources before proceeding with planning. NEVER make assumptions, inferences, or guesses about ticket or PR content if access fails.** - -### Access failure procedure - -If access to JIRA or Git fails during planning: - -1. Reset to default: `set -a && source ~/.env && set +a` and retry -2. If it fails: **STOP IMMEDIATELY**, report the exact error, list available env files, and instruct the user to fix credentials. Never guess or infer content. - -### Why this matters - -Proceeding with incorrect or assumed information leads to: -- Documentation plans that do not match the actual feature/bug/change -- Wasted effort planning irrelevant content -- Incorrect plans that must be completely redone -- Loss of user trust in the workflow - -**It is ALWAYS better to stop and wait for correct access than to produce incorrect plans.** - -## Jobs to Be Done (JTBD) framework - -You must apply a Jobs to Be Done mindset to all documentation planning. This means shifting from "what the product does" (feature-focused) to "what the user is trying to accomplish" (outcome-focused). Prioritize the user's underlying motivation—the reason they "hire" the product—over technical specifications. - -### Why JTBD matters for documentation planning - -Applying JTBD to documentation planning produces measurable improvements: - -- **Reduces topic proliferation**: Unless a new feature corresponds to a genuinely new user job, new enhancements are updates to existing job-based topics — not new parent topics. -- **Addresses emotional and social dimensions**: Jobs have functional, emotional, and social aspects. Users want peace of mind, to feel secure, and to look competent to their peers. Documentation that acknowledges these dimensions (e.g., "reliably," "with confidence," "without risking data loss") resonates more strongly than purely functional descriptions. -- **Improves AI and search discoverability**: As documentation is ingested by AI and search engines, outcome-focused content surfaces solutions for users trying to resolve their business problems — not just product names. -- **Reduces support queries**: Intuitive, job-aligned documentation reduces mental effort and frustration, leading to fewer support tickets. -- **Creates timeless structure**: Jobs do not change over time. While the technology used to accomplish them evolves, the fundamental user need remains the same — making JTBD-organized documentation inherently stable. - -### Core JTBD principles - -1. **Organize by outcomes, not features**: Structure documentation around user goals ("Top Jobs") rather than internal product modules or feature names. - -2. **Follow the JTBD hierarchy**: Implement a three-level structure: - - **Category** → **Top Job (Parent Topic)** → **User Story (Specific Task)** - -3. **Frame the user's job**: Before planning any content, identify the job statement: - - "When [situation], I want to [motivation], so I can [expected outcome]" - - This job statement informs planning decisions but does NOT appear in final documentation - -4. **Distinguish JTBD from User Stories**: JTBD and user stories are complementary but distinct: - - | Dimension | JTBD | User Story | - |-----------|------|------------| - | Format | "When [situation], I want to [motivation], so I can [outcome]" | "As a [user], I want [goal] so that [benefit]" | - | Focus | **What** the user wants to achieve + **Why** it matters | **How** the user will use a specific feature | - | Scope | High-level, broad — overarching user goals | Detailed, specific — single actionable task | - | Maps to | Top Jobs (Parent Topics) | Level 3 tasks (child modules) | - - A single JTBD contains multiple user stories. Use JTBD to define navigation and parent topics; use user stories to plan the child modules within each parent topic. - -5. **Use natural language**: Avoid product-specific buzzwords or internal vocabulary. Use terms users naturally use when searching for solutions. - -6. **Draft outcome-driven titles**: - - **Bad**: "Ansible Playbook Syntax" (feature-focused) - - **Good**: "Define automation workflows" (outcome-focused) - -7. **Apply active phrasing**: Use imperatives and task-oriented verbs (e.g., "Set up," "Create," "Control") and state the context or benefit when helpful. - -8. **Use industry-standard terminology when appropriate**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable in titles and content. Avoid *product-specific* vocabulary (e.g., internal feature names), but do not avoid universally understood technical terms. - -9. **State the benefit or context in titles**: When two titles could sound similar, add context to differentiate: - - **Bad**: "Managing Roles and Permissions" - - **Good**: "Control team access with roles and permissions" - - Technique: reverse-engineer titles from job statements. Write the user story ("As a [user], I want to [goal], so that I can [benefit]"), then extract a title from the goal and benefit. - - User story: "As a project manager, I want to export task reports so I can review team progress." - - Title: "Review team progress by exporting task reports" - -10. **Use only approved JTBD categories**: Structure documentation according to the following defined Categories. Do not create new categories. - - What’s new - - Discover - - Get started - - Plan - - Install - - Upgrade - - Migrate - - Administer - - Develop - - Configure - - Secure - - Observe - - Integrate - - Optimize - - Extend - - Troubleshoot - - Reference - -## Doc impact assessment - -Before planning documentation, assess the documentation impact of each requirement, JIRA ticket, or PR. This determines what needs documentation and at what priority. - -### Impact grades - -| Grade | Criteria | Examples | -|-------|----------|----------| -| **High** | Major new features, architecture changes, new APIs, breaking changes, new user-facing workflows | New operator install method, API v2 migration, new UI dashboard | -| **Medium** | Enhancements to existing features, new configuration options, changed defaults, deprecations | New CLI flag, updated default timeout, deprecated parameter | -| **Low** | Minor UI text changes, small behavioral tweaks, additional supported values | New enum value, updated error message text | -| **None** | Internal refactoring, test-only changes, CI/CD changes, dependency bumps, code cleanup | Test coverage increase, linter fixes, internal module rename | - -### Special handling - -- **QE/testing issues**: Grade as None unless they reveal user-facing behavioral changes (e.g., a test failure that exposed an undocumented constraint) -- **Security fixes (CVEs)**: Grade as High if they require user action (config change, upgrade steps); Medium if automatic with no user action needed -- **Bug fixes**: Grade based on whether the fix changes documented behavior or requires updated instructions - -### When to apply - -Run doc impact assessment as the **first analytical step** when multiple issues or PRs are provided. Filter out None-impact items early so planning focuses on items that produce user-facing documentation. - -## When invoked - -1. Gather and summarize sources: - - Read existing documentation structure in the repository - - Analyze the codebase to understand features and functionality - - Query JIRA for relevant tickets if project/sprint information is provided - - Review any engineering requirements or specifications provided - - **Track all source URLs** as you research (JIRA tickets, PRs, code files, external docs) - - **Summarize each source** before planning (see Source summarization below) - -2. Assess documentation impact: - - Grade each requirement/issue using the doc impact assessment criteria - - Filter out None-impact items - - Prioritize High and Medium impact items for planning - -3. Analyze documentation gaps: - - Compare existing docs against codebase features - - Identify undocumented or under-documented areas - - Note outdated content that needs updating - -4. Create a documentation plan with: - - Recommended module structure (concepts, procedures, references) - - Assembly organization for user stories - - Priority ranking for documentation tasks - - Dependencies between documentation pieces - - **Reference links** to source materials for each recommendation - -5. Verify output before delivering (see Self-review verification below) - -6. Save all planning output and intermediary files to `.claude/docs/` - -## Reference tracking - -As you research, maintain a list of all URLs and file paths consulted. Include these references inline with the relevant planning recommendations. - -**Types of references to track:** -- JIRA ticket URLs (e.g., `https://redhat.atlassian.net/browse/PROJECT-123`) -- GitHub/GitLab PR URLs (e.g., `https://github.com/org/repo/pull/456`) -- Code file paths (e.g., `src/components/feature.ts:45-67`) -- Existing documentation paths (e.g., `docs/modules/existing-guide.adoc`) -- External documentation URLs (e.g., upstream API docs, specifications) -- Style guide references (e.g., `/style-guides/supplementary/terminology.adoc`) - -## Planning methodology - -### 1. Discovery phase - -Gather information from multiple sources. **Record all URLs and file paths as you research.** - -**Codebase analysis:** -- Identify key features, APIs, and components -- Find configuration options and parameters -- Locate example code and usage patterns -- Record file paths with line numbers (e.g., `src/feature.ts:45-67`) - -**Existing documentation:** -- Map current module structure -- Identify gaps and outdated content -- Note reusable snippets and content -- Record documentation file paths - -**JIRA tickets:** -- Query for documentation-related issues -- Find feature tickets that need documentation -- Identify user-reported documentation gaps -- Record JIRA URLs for each relevant ticket - -**Pull requests / Merge requests:** -- Review recent merged PRs for new features -- Check PR descriptions for context -- Record PR URLs with titles - -**Requirements:** -- Parse engineering specifications -- Extract user stories requiring documentation -- Identify new features to document -- Record links to specification documents - -**External sources:** -- Upstream documentation -- API specifications -- Industry standards -- Record all external URLs consulted - -**Source summarization:** - -Before proceeding to analysis, create a structured summary of each source. This ensures planning is grounded in facts, not assumptions. - -- Summarize each source (ticket, PR, spec) into a dense factual summary (max 150 words per source) -- Focus on: user-facing changes, API/config changes, new or removed capabilities, documentation signals -- Be faithful to the source data — do not invent or infer information not present in the source -- Flag ambiguous or incomplete sources for follow-up - -**Relationship and overlap analysis** (when multiple issues/requirements exist): - -When analyzing multiple issues, PRs, or requirements, assess their relationships before planning modules: - -- **Content overlap**: Do multiple issues describe the same user-facing change from different angles? -- **Dependencies**: Must one issue be documented before another makes sense? -- **Duplication risk**: Could separate issues produce near-identical documentation? -- **Boundary clarity**: Is it clear which issue "owns" which documentation? -- **User journey connections**: Do issues form a sequence in a user's workflow? - -Classify each relationship pair: - -| Relationship | Description | -|-------------|-------------| -| Sequential | Issue B depends on Issue A being documented first | -| Parallel/Sibling | Issues cover related but distinct topics at the same level | -| Overlapping | Issues share significant content scope — consolidation needed | -| Complementary | Issues cover different aspects of the same feature | -| Independent | Issues have no meaningful documentation relationship | - -Surface overlap risks early and recommend documentation ownership boundaries to avoid duplicate content. - -### 2. Gap analysis - -Compare discovered content against documentation needs: - -| Category | Questions to answer | -|----------|---------------------| -| Coverage | What features lack documentation? | -| Currency | What docs are outdated? | -| Completeness | What procedures lack verification steps? | -| Structure | Are modules properly typed (CONCEPT/PROCEDURE/REFERENCE)? | -| User stories | What user journeys are incomplete? | - -### 3. Content journey mapping - -JTBD provides the **why** — the user's underlying motivation and desired outcome. Content journeys provide the **how** and **where** — the specific steps a user takes and where content can best assist them. Always define the JTBD first (Step 1), then use content journeys to identify lifecycle gaps — areas where documentation exists for advanced use but is missing for initial discovery, or vice versa. - -#### The 5-phase content journey - -| Phase | User mindset | Documentation purpose | Examples | -|-------|-------------|----------------------|----------| -| **Expand** | Discovery, awareness, first impressions | Help users understand the product exists and what problem it solves | Landing pages, overviews, "what is X" concepts | -| **Discover** | Understanding the technology, evaluating fit | Help users evaluate whether the product fits their needs | Architecture overviews, comparison guides, feature lists | -| **Learn** | Hands-on trial, tutorials, guided experience | Help users get started and build initial competence | Getting started guides, tutorials, quickstarts | -| **Evaluate** | Committing to the solution, early production use | Help users move from trial to production | Installation, configuration, migration procedures | -| **Adopt** | Day-to-day use, optimization, advocacy | Help users operate, optimize, and troubleshoot | Operations guides, troubleshooting, API references | - -#### How to apply - -- After planning modules, tag each with its primary journey phase -- Identify phase gaps: strong Learn content but weak Expand content suggests users can follow tutorials but cannot discover the product -- Use phase distribution to inform prioritization — a product with no Expand content may need high-priority overview modules - -### 4. Module planning with JTBD - -For each documentation need, first identify the user's job: - -**Step 1: Define the job statement** (internal planning only) -- "When [situation], I want to [motivation], so I can [expected outcome]" -- Example: "When I have a new application ready for deployment, I want to configure the runtime environment, so I can run my application reliably in production." - -**Step 1b: Check for existing jobs before creating new parent topics** -- Before creating a new parent topic, check whether the user's goal is already covered by an existing job in the documentation. -- Unless a new feature corresponds to a genuinely new user job, it should be an update to an existing job-based topic — not a new parent topic. -- Only create a new parent topic when the user's goal is fundamentally distinct from all existing jobs. -- This prevents topic proliferation and keeps the documentation structure stable over time. - -**Step 2: Map to the JTBD hierarchy** -- **Category**: Broad area, must be selected from the defined list -- **Top Job / Parent Topic**: The user's main goal (e.g., "Deploy applications to production") -- **User Stories / Tasks**: Specific steps to achieve the goal (e.g., "Configure the runtime," "Set up monitoring") - -TOC nesting rules: -- Headings in TOCs must not exceed **3 levels** of nesting. -- **Categories do not count** toward nesting depth because they contain no content — they are organizational groupings only. -- Example: `Configure (category) → Control access to resources (Top Job, level 1) → Set up RBAC (user story, level 2) → RBAC configuration options (reference, level 3)` - -**Step 3: Plan Parent Topics** - -Every major job must have a Parent Topic that serves as the starting point for users looking to achieve the desired outcome. Parent Topic descriptions serve both human readers and AI/search engines — including "the what" and "the why" helps both audiences find the right content. - -Parent Topics must include: -- A product-agnostic title using natural language (this becomes the TOC entry for the job) -- A description of "the what" (the desired outcome) and "the why" (the motivation/benefit) -- A high-level overview of how the product helps users achieve this specific goal -- An overview of the high-level steps to achieve the goal, with links to related content - -Example Parent Topic outline: -``` -Title: Improve application performance -Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. -Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. -High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results -``` - -**Step 4: Recommend module types** -- CONCEPT - For explaining what something is and why it matters (supports understanding the job) -- PROCEDURE - For step-by-step task instructions (helps complete the job) -- REFERENCE - For lookup data (tables, parameters, options) (supports job completion) - -**Step 5: Assembly organization** -- Group related modules into user story assemblies organized by Top Jobs -- Define logical reading order based on job completion flow -- Identify shared prerequisites - -### 5. Theme clustering - -When analyzing multiple related issues or requirements, group them into thematic clusters before planning individual modules. Clustering prevents fragmented documentation and reveals natural assembly boundaries. - -**For each cluster:** -- **Title**: A descriptive name for the theme (e.g., "Authentication and access control") -- **Summary**: 1-2 sentences describing the shared scope -- **Issues included**: List of JIRA tickets, PRs, or requirements in this cluster -- **Overlap risk**: Low / Medium / High — how much content overlap exists within the cluster -- **Recommended ownership**: Which assembly or parent topic should own this cluster's documentation - -Clusters feed directly into assembly and parent topic organization. A cluster with High overlap risk should be consolidated into fewer modules rather than producing one module per issue. - -### 6. Prioritization - -Rank documentation work by: -1. **Critical** - Blocks users from core functionality -2. **High** - Important features lacking documentation -3. **Medium** - Improvements to existing documentation -4. **Low** - Nice-to-have enhancements - -Factor in doc impact grades when prioritizing: High-impact items with Critical priority are the top planning targets. - -## Self-review verification - -Before delivering the final plan, verify your own output against these checks. Do not skip this step. - -### Verification checklist - -| Check | What to verify | -|-------|---------------| -| **No placeholder syntax** | No `[TODO]`, `[TBD]`, `[REPLACE]`, ``, or `{variable}` in the output. No unreplaced `[bracketed instructions]` from templates. | -| **No hallucinated content** | Every recommendation is traceable to a source you actually read | -| **Source traceability** | Each module recommendation links to at least one source (JIRA, PR, code, or doc) | -| **No sensitive information** | No hostnames, passwords, IPs, internal URLs, or tokens in the output | -| **Persona limit** | Maximum 3 user personas identified — more indicates insufficient consolidation | -| **Template completeness** | All required output sections are present and populated | -| **Impact consistency** | Doc impact grades align with the prioritization of recommended modules | -| **Journey coverage** | Content journey phase mapping is included and has no unexplained gaps | -| **JIRA description** | JIRA description template is fully populated — no `[REPLACE]` markers, no bracketed placeholder instructions, no example entries left unreplaced, persona reference list not included in output | - -### If verification fails - -Fix the issue before saving. If you cannot fix it (e.g., a source is ambiguous), add a note in the Implementation notes section explaining the limitation rather than guessing. - -## Output location - -Save all planning output and intermediary files to the `.claude/docs/` directory: - -``` -.claude/docs/ -├── plans/ # Documentation plans -│ └── plan__.md -├── gap-analysis/ # Gap analysis reports -│ └── gaps__.md -└── research/ # Research and discovery notes - └── discovery__.md -``` - -Create the `.claude/docs/` directory structure if it does not exist. Saving intermediary files allows users to review and edit planning outputs before proceeding to documentation work. - -## Output format - -The planner produces two outputs from the same research: a full documentation plan (saved as an attachment) and an abbreviated JIRA ticket description (posted to the ticket). Both are populated from your research and analysis — **you MUST replace every `[REPLACE: ...]` marker** with actual content. Never output bracket instructions, placeholder text, or the persona reference list. - -### 1. Full documentation plan (attachment) - -Save the fully populated template below to the output path specified in the workflow prompt. When invoked by the orchestrator, this is `/planning/plan.md`; when invoked by the legacy command, save to `.claude/docs/plans/plan__.md`. This is the comprehensive planning artifact with all sections completed. - -### 2. JIRA ticket description - -Post **only these sections** from the full plan to the JIRA ticket description: - -- `## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?` -- `## How does the JTBD(s) relate to the overall real-world workflow for the user?` -- `## Who can provide information and answer questions?` -- `## New Docs` -- `## Updated Docs` - -Copy these five sections verbatim from the completed full plan. Do not add sections that are not in this list to the JIRA ticket description. The full plan attachment contains the remaining detail. - -### Documentation plan template - -**Critical rules for template population:** -- **Replace ALL `[REPLACE: ...]` text** with real content derived from your research — never output the bracket instructions themselves -- **Personas**: Select 1-3 personas from the persona reference list below. Output ONLY the selected personas with a brief relevance note. Do NOT include the full persona reference list in the output -- **New Docs / Updated Docs**: Replace the example entries with actual module names, types, and content outlines from your planning. The entries shown (e.g., "Actual Module Title (Concept)") are structural examples, not headings to keep -- **JTBD statement**: Replace `[actual circumstance]`, `[actual motivation]`, etc. with the real job statement from your analysis - -```markdown -# Documentation Plan - -**Project**: [REPLACE: Project name from JIRA ticket] -**Date**: [REPLACE: Current date in YYYY-MM-DD format] -**Ticket**: [REPLACE: JIRA ticket ID and URL] - -## What is the support status of the feature(s) being used to complete the user's JTBD (Job To Be Done)? - -[REPLACE: Choose one of Dev Preview / Tech Preview / General Availability based on JIRA ticket metadata] - -## Why is this content important? - -[REPLACE: Summarize why the user needs this content, derived from your JTBD analysis] - -## Who is the target persona(s)? - -[REPLACE: List 1-3 selected personas with brief relevance notes. Example output:] -[* Developer: Primary user creating containerized applications] -[* SysAdmin: Manages the platform where containers are deployed] - -## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided? - -[REPLACE: Write the completed job statement using your research findings] -When [actual circumstance], I want to [actual motivation], so that I can [actual goal] while avoiding [actual pain point]. - -## How does the JTBD(s) relate to the overall real-world workflow for the user? - -[REPLACE: Explain how the JTBD fits into the user's broader end-to-end workflow] - -## What high level steps does the user need to take to accomplish the goal? - -[REPLACE: Provide the actual steps and prerequisites identified during your planning] - -## Is there a demo available or can one be created? - -[REPLACE: No / Yes — include link if available] - -## Are there special considerations for disconnected environments? - -[REPLACE: No / Yes — describe considerations if applicable] - -## Who can provide information and answer questions? - -[REPLACE: Extract PM / Technical SME / UX contacts from the parent JIRA ticket] - -## Release Note needed? - -[REPLACE: No / Yes] - -Draft release note: [REPLACE: Draft a release note based on the user-facing change, or N/A] - -## Links to existing content - -[REPLACE: Add actual links discovered during research as bullets] - -## New Docs - -[REPLACE: List actual new modules to create based on your gap analysis and module planning. Follow this structure for each:] - -* Actual Module Title (Concept/Procedure/Reference) - Actual content outline derived from your research - -## Updated Docs - -[REPLACE: List actual existing modules that need updates based on your gap analysis. Follow this structure for each:] - -* actual-existing-filename.adoc - Specific updates required based on your findings -``` - -### Persona reference list - -Select 1-3 personas from this list when populating the "Who is the target persona(s)?" section. Do NOT include this list in the output. - -| Persona | Description | -|---------|-------------| -| C-Suite IT | The ultimate budget owner and final decision-maker for technology purchases, focused on cloud migration, cost efficiency, and finding established vendors with strong reputations. | -| C-Suite Non-IT | Holds significant budget influence and focuses on ROI and digital transformation, but relies on IT to vet the technical integration and security capabilities of new solutions. | -| AppDev ITDM | Typically owns the budget for application and cloud infrastructure, prioritizing innovation in cloud-native development and automation to improve customer and employee experiences. | -| Enterprise Architect | A technical influencer rather than a budget owner, they focus on how new automation and cloud solutions will integrate with and support the existing infrastructure. | -| IT Operations Leader | Owns the budget for IT infrastructure and operations, prioritizing security, virtualization, and cloud migration to ensure system stability and end-user satisfaction. | -| Line of Business (LOB) | Budget owners for specific business units (like Marketing or Sales) who focus on customer satisfaction and operational efficiency, often requiring proof of successful implementation. | -| SysAdmin | Influences purchasing by recommending specific solutions to modernize infrastructure, focusing heavily on automation and virtualization even though they do not own the budget. | -| Procurement | A budget owner or influencer who researches vendors to ensure cost savings and compliance, requiring detailed support information to justify recommendations to internal business units. | -| Developer | Focused on creating solutions using tools like APIs and Kubernetes, they act as influencers who value technical specs and community support rather than managing budgets or making final decisions. | -| Data Scientist | Influences purchases for data and development platforms, driven by a passion for AI/ML and big data analytics to drive innovation and strategic decision-making. | -| IT Security Practitioner / Compliance & Auditor | Often a budget owner involved throughout the process, prioritizing data protection, risk mitigation, and identity management to prevent security breaches. | -| Automation Architect | A budget owner or influencer for Engineering and IT, motivated by creative problem-solving and focused on implementing automation, big data, and cloud computing technologies. | -| Network Architect (Telco) | A budget owner involved in the entire purchase process, deeply focused on migrating to 5G, automation, and cloud technologies to stay ahead in a changing market. | -| Network Admin/Ops (Telco) | Recommends vendors and defines capabilities with a focus on automating network operations and resolving customer issues quickly, though rarely the final decision-maker. | -| Head of Product Line (FinServ) | Sets strategy for their specific line of business and is open to pioneering technologies that innovate the business, despite operating in a culture often resistant to change. | - -### How to populate the template - -- **Support status**: Determine from JIRA ticket labels, fix version, or parent epic metadata. If not explicitly stated, flag for confirmation. -- **Why important**: Derive from the JTBD analysis — explain the user value, not the feature description. -- **Target personas**: Select from the persona reference list above based on who the JTBD applies to. Limit to 3 personas maximum per the self-review verification checklist. -- **JTBD statement**: Use the job statement from your JTBD analysis. Must follow the "When... I want to... so that I can..." format with all placeholders replaced. -- **High level steps**: Extract from your procedure module planning. Include prerequisites identified during gap analysis. -- **Contacts**: Extract PM, SME, and UX contacts from the parent JIRA ticket fields (assignee, reporter, watchers, or custom fields). -- **Release note**: Check the JIRA ticket for release note fields or labels. Draft a release note based on the user-facing change. -- **Links to existing content**: Include links to existing documentation, upstream docs, and related JIRA tickets discovered during research. -- **New Docs / Updated Docs**: Map directly from your recommended modules and gap analysis sections. Use actual module names and real content outlines — not the example entries from the template. - -## Using skills - -### Accessing style guides -Read style guide files directly from the local docs-guidelines directory (set `DOCS_GUIDELINES_PATH` or use default `$HOME/docs-guidelines`): -- Red Hat supplementary style guide: `${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/` -- Red Hat modular documentation guide: `${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/modular-docs/` -- LLM-optimized summaries: `llms.txt` files in each directory - -### Querying JIRA -Use the jira-reader script to query JIRA issues. - -**Fetch issue details:** -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --issue PROJ-123 -``` - -**Fetch issue with comments:** -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --issue PROJ-123 --include-comments -``` - -**Search issues by JQL:** -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --jql 'project=PROJ AND fixVersion=1.0.0' -``` - -**Search with full details:** -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/jira-reader/scripts/jira_reader.py --jql 'project=PROJ AND labels=docs-needed' --fetch-details -``` - -### Reviewing GitHub/GitLab PRs -Use the git PR reader script to extract code changes from PRs/MRs. - -``` -# View PR/MR details as JSON -python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py info --json - -# List changed files with stats -python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py files --json - -# View PR/MR diff -python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py diff -``` - -Requires tokens in `~/.env`: -- `GITHUB_TOKEN` for GitHub PRs -- `GITLAB_TOKEN` for GitLab MRs - -### Reading Red Hat documentation with redhat-docs-toc - -Research existing Red Hat documentation to understand patterns and gaps. Extract article URLs from documentation TOC pages: - -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/redhat-docs-toc/scripts/toc_extractor.py --url "https://docs.redhat.com/en/documentation/product/version/html/guide/index" -``` - -### Extracting article content with article-extractor - -Download and analyze existing Red Hat documentation for planning. Extract article content as markdown: - -```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." -``` - -Use these skills to: -- Research existing documentation patterns -- Identify gaps in current coverage -- Understand the documentation structure for similar products -- Extract reference content for analysis - -## Key principles - -1. **Impact-driven prioritization**: Grade documentation impact before planning — assess what needs docs and at what priority before committing to a plan -2. **Jobs to Be Done**: Plan documentation around what users are trying to accomplish, not what the product does -3. **Content journey awareness**: Map documentation to user lifecycle phases (Expand, Discover, Learn, Evaluate, Adopt) to identify coverage gaps -4. **Outcome-focused titles**: Use natural language that describes user goals, not feature names -5. **Parent Topics first**: Every major user job needs a Parent Topic that maps the path to success -6. **Topic proliferation control**: Do not create new parent topics for features that fit within an existing job — only create new parent topics for genuinely new user goals -7. **JTBD before content journeys**: Define the user's job (the why) before mapping content journeys (the how/where) -8. **Modular thinking**: Plan for reusable, self-contained modules that support job completion -9. **Progressive disclosure**: Plan simpler content before advanced topics -10. **Maintainability**: Consider long-term maintenance burden in recommendations -11. **Minimalism**: Only plan documentation that provides clear user value -12. **Traceable recommendations**: Every recommendation must link to its source (JIRA, PR, code, or external doc) -13. **Self-verified output**: Verify your own output against the verification checklist before delivering — no placeholders, no hallucinated content, all recommendations traceable diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index cfec524e..93fec008 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -1,6 +1,6 @@ --- name: docs-planner -description: Use PROACTIVELY when planning documentation structure, performing gap analysis, or creating documentation plans. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with feature-based information architecture. MUST BE USED for any documentation planning or content architecture task. +description: Use PROACTIVELY when planning documentation structure, performing gap analysis, or creating documentation plans. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans. Supports multiple content paradigms (JTBD, user-stories) via runtime reference files. MUST BE USED for any documentation planning or content architecture task. tools: Read, Glob, Grep, Edit, Bash, Skill, WebSearch, WebFetch skills: docs-tools:jira-reader, docs-tools:article-extractor, docs-tools:redhat-docs-toc --- @@ -30,46 +30,23 @@ Proceeding with incorrect or assumed information leads to: **It is ALWAYS better to stop and wait for correct access than to produce incorrect plans.** -## Feature-based information architecture +## Content paradigm -Structure documentation around product capabilities, features, and components — reflecting how the product is built and how users interact with it. Use user stories to scope individual documentation modules. +The task prompt specifies which content paradigm to use. Before planning, read the corresponding paradigm reference file and apply its principles throughout your planning process. -### Why feature-based organization works +| Paradigm | Reference file | +|----------|---------------| +| `jtbd` (default) | Read `plugins/docs-tools/reference/paradigm-jtbd.md` — "For planners" section | +| `user-stories` | Read `plugins/docs-tools/reference/paradigm-user-stories.md` — "For planners" section | -- **Matches the product mental model**: Users often approach documentation by feature name or component — organizing around these terms aligns with how they search and navigate. -- **Scales with the product**: As features are added, new sections are added naturally without restructuring the entire documentation hierarchy. -- **Direct mapping to engineering**: Features and components map directly to engineering teams, code modules, and release notes — making collaboration and maintenance straightforward. -- **Clear ownership boundaries**: Each feature section has a clear scope, reducing ambiguity about where new content belongs. +If the task prompt does not specify a paradigm, default to `jtbd`. -### Core principles - -1. **Organize by features and components**: Structure documentation around product capabilities, features, and components rather than abstract user goals. - -2. **Follow the feature-based hierarchy**: Implement a three-level structure: - - **Area** → **Feature (Parent Topic)** → **Task (Specific Procedure or Concept)** - -3. **Use user stories for scoping**: Before planning any content, identify the user story: - - "As a [role], I want [goal] so that [benefit]" - - User stories determine which modules to create and what content to include - -4. **Dynamic categories**: Derive categories from the product's domain and feature landscape. Common patterns include: - - Component-based: "Authentication", "Networking", "Storage", "Monitoring" - - Lifecycle-based: "Installation", "Configuration", "Administration", "Troubleshooting" - - Audience-based: "Developer Guide", "Operator Guide", "API Reference" - - Choose the categorization scheme that best fits the product and its users. Do not use a fixed category list — adapt to the product domain. - -5. **Use descriptive, feature-focused titles**: - - **Good**: "Configuring horizontal pod autoscaling" (clear feature reference) - - **Bad**: "Scale applications based on demand" (too abstract) - -6. **Apply active phrasing for procedures**: Use imperatives and name the feature (e.g., "Configure RBAC policies", "Install the monitoring agent"). - -7. **Use industry-standard terminology**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable. Avoid product-specific internal vocabulary. - -8. **Feature-scoped parent topics**: Each major feature or component gets a parent topic that introduces the feature, explains its purpose, and links to tasks within it. - -9. **User stories for child modules**: Each feature's child modules correspond to specific user stories that exercise that feature. +The paradigm reference determines: +- Information architecture hierarchy and category scheme +- Module planning methodology (job statements vs user stories) +- Title conventions (outcome-focused vs feature-descriptive) +- Plan template variant (which paradigm-specific sections to use) +- Key principles emphasis ## Doc impact assessment @@ -241,55 +218,23 @@ Content journeys map the specific steps a user takes through a feature's lifecyc - Identify phase gaps: strong Learn content but weak Expand content suggests users can follow tutorials but cannot discover the feature - Use phase distribution to inform prioritization — a feature with no Expand content may need high-priority overview modules -### 4. Module planning with user stories +### 4. Module planning -For each documentation need, identify the user story and map it to the feature hierarchy: - -**Step 1: Define the user story** (internal planning only) -- "As a [role], I want [goal] so that [benefit]" -- Example: "As a cluster administrator, I want to configure horizontal pod autoscaling so that my applications handle variable traffic without manual intervention." - -**Step 1b: Check for existing feature topics before creating new parent topics** -- Before creating a new parent topic, check whether the feature is already covered by an existing parent topic in the documentation. -- New capabilities within an existing feature should be added as child modules under the existing parent topic — not as new parent topics. -- Only create a new parent topic when the feature is genuinely new and distinct from all existing documented features. - -**Step 2: Map to the feature hierarchy** -- **Area**: Broad domain derived from the product (e.g., "Networking", "Security", "Storage") -- **Feature / Parent Topic**: The specific capability (e.g., "Horizontal Pod Autoscaler") -- **Tasks / Child Modules**: Specific procedures, concepts, and references for the feature (e.g., "Configuring HPA thresholds", "HPA architecture", "HPA parameters") - -TOC nesting rules: -- Headings in TOCs must not exceed **3 levels** of nesting. -- **Areas do not count** toward nesting depth because they contain no content — they are organizational groupings only. -- Example: `Networking (area) → Ingress Controller (Feature, level 1) → Configuring route timeouts (task, level 2) → Route timeout parameters (reference, level 3)` - -**Step 3: Plan Parent Topics** - -Every major feature must have a Parent Topic that introduces the feature to users. Parent Topic descriptions serve both human readers and AI/search engines. - -Parent Topics must include: -- A clear, descriptive title naming the feature or component -- A description of what the feature does and when to use it -- An overview of the feature's architecture or key components -- An overview of common tasks and their sequence, with links to related content - -Example Parent Topic outline: -``` -Title: Horizontal pod autoscaler -Description: [What] Automatically adjusts the number of pod replicas based on CPU, memory, or custom metrics. [When] Use when workloads have variable resource demands. -Overview: The HPA controller monitors metrics and adjusts replica counts within configured bounds. -Common tasks: 1. Configure HPA for a deployment → 2. Set custom metrics → 3. Monitor scaling events -``` +Follow the module planning methodology defined in the paradigm reference file you read in the "Content paradigm" section. The paradigm determines: +- How to define scoping statements (job statements vs user stories) +- How to check for existing topics before creating new parent topics +- How to map to the paradigm's hierarchy (categories, parent topics, child modules) +- How to plan parent topics (outcome-focused vs feature-descriptive) +- TOC nesting rules -**Step 4: Recommend module types** -- CONCEPT - For explaining what a feature is, how it works, and when to use it -- PROCEDURE - For step-by-step task instructions for configuring or using the feature +**Recommend module types** (shared across paradigms): +- CONCEPT - For explaining what something is, how it works, and when to use it +- PROCEDURE - For step-by-step task instructions - REFERENCE - For lookup data (parameters, options, API endpoints, return codes) -**Step 5: Assembly organization** -- Group related modules into assemblies organized by feature -- Define logical reading order based on task dependencies +**Assembly organization** (shared across paradigms): +- Group related modules into assemblies organized by the paradigm's parent topics +- Define logical reading order based on dependencies - Identify shared prerequisites ### 5. Theme clustering @@ -363,15 +308,13 @@ Save the fully populated template below to the output path specified in the work ### 2. JIRA ticket description -Post **only these sections** from the full plan to the JIRA ticket description: +Post **only** the paradigm-specific sections plus the shared sections from the full plan to the JIRA ticket description. The paradigm reference file specifies which sections to include. The shared sections are always: -- `## What are the primary user stories?` -- `## How do these features relate to the user's workflow?` - `## Who can provide information and answer questions?` - `## New Docs` - `## Updated Docs` -Copy these five sections verbatim from the completed full plan. Do not add sections that are not in this list to the JIRA ticket description. The full plan attachment contains the remaining detail. +Copy these sections verbatim from the completed full plan. Do not add sections that are not in this list to the JIRA ticket description. The full plan attachment contains the remaining detail. ### Documentation plan template @@ -390,11 +333,12 @@ Copy these five sections verbatim from the completed full plan. Do not add secti ## What is the support status of the feature(s)? -[REPLACE: Choose one of Dev Preview / Tech Preview / General Availability based on JIRA ticket metadata] +[REPLACE: Choose one of Dev Preview / Tech Preview / General Availability based on JIRA ticket metadata. +Use the paradigm-specific header variant from the paradigm reference if applicable.] ## Why is this content important? -[REPLACE: Summarize why the user needs this content, derived from your analysis of the features and user stories] +[REPLACE: Summarize why the user needs this content, derived from your analysis] ## Who is the target persona(s)? @@ -402,13 +346,17 @@ Copy these five sections verbatim from the completed full plan. Do not add secti [* Developer: Primary user creating containerized applications] [* SysAdmin: Manages the platform where containers are deployed] -## What are the primary user stories? +## [Paradigm-specific section 1] -[REPLACE: List the key user stories in "As a [role], I want [goal] so that [benefit]" format, derived from your research] +[REPLACE: Use the section header and content format from the paradigm reference file. +For JTBD: "What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?" +For user-stories: "What are the primary user stories?"] -## How do these features relate to the user's workflow? +## [Paradigm-specific section 2] -[REPLACE: Explain how the documented features fit into the user's broader end-to-end workflow] +[REPLACE: Use the section header and content format from the paradigm reference file. +For JTBD: "How does the JTBD(s) relate to the overall real-world workflow for the user?" +For user-stories: "How do these features relate to the user's workflow?"] ## What high level steps does the user need to take to accomplish the goal? @@ -476,9 +424,9 @@ Select 1-3 personas from this list when populating the "Who is the target person ### How to populate the template - **Support status**: Determine from JIRA ticket labels, fix version, or parent epic metadata. If not explicitly stated, flag for confirmation. -- **Why important**: Explain the user value based on the features and user stories — what problems do users face without this content? -- **Target personas**: Select from the persona reference list above based on who the user stories apply to. Limit to 3 personas maximum per the self-review verification checklist. -- **User stories**: Use the user stories from your analysis. Must follow the "As a [role], I want [goal] so that [benefit]" format with all placeholders replaced. +- **Why important**: Explain the user value — what problems do users face without this content? +- **Target personas**: Select from the persona reference list above. Limit to 3 personas maximum per the self-review verification checklist. +- **Paradigm-specific sections**: Populate using the section headers and content format from the paradigm reference file. For JTBD, use job statements; for user-stories, use "As a [role], I want [goal] so that [benefit]" format. All placeholders must be replaced. - **High level steps**: Extract from your procedure module planning. Include prerequisites identified during gap analysis. - **Contacts**: Extract PM, SME, and UX contacts from the parent JIRA ticket fields (assignee, reporter, watchers, or custom fields). - **Release note**: Check the JIRA ticket for release note fields or labels. Draft a release note based on the user-facing change. @@ -559,10 +507,10 @@ Use these skills to: ## Key principles 1. **Impact-driven prioritization**: Grade documentation impact before planning — assess what needs docs and at what priority before committing to a plan -2. **Feature-based organization**: Plan documentation around product features and components, organized by how users interact with them +2. **Content paradigm alignment**: Apply the principles from the paradigm reference file — organize documentation according to the paradigm's hierarchy, titling, and scoping methodology 3. **Content journey awareness**: Map documentation to user lifecycle phases (Expand, Discover, Learn, Evaluate, Adopt) to identify coverage gaps -4. **Descriptive titles**: Use clear, feature-descriptive titles that name the capability or component -5. **Parent Topics first**: Every major feature needs a Parent Topic that introduces the capability and links to tasks +4. **Parent Topics first**: Every major topic needs a Parent Topic that introduces the subject and links to tasks +5. **Topic proliferation control**: Do not create new parent topics when the content fits within an existing parent topic 6. **Modular thinking**: Plan for reusable, self-contained modules 7. **Progressive disclosure**: Plan simpler content before advanced topics 8. **Maintainability**: Consider long-term maintenance burden in recommendations diff --git a/plugins/docs-tools/agents/docs-writer-jtbd.md b/plugins/docs-tools/agents/docs-writer-jtbd.md deleted file mode 100644 index 73c715e4..00000000 --- a/plugins/docs-tools/agents/docs-writer-jtbd.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -name: docs-writer-jtbd -description: Use PROACTIVELY when writing or drafting documentation with JTBD (Jobs-to-Be-Done) methodology. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules with outcome-focused titles in AsciiDoc (default) or Material for MkDocs Markdown format. MUST BE USED for JTBD-based documentation writing. -tools: Read, Write, Glob, Grep, Edit, Bash, Skill -skills: docs-tools:jira-reader, vale-tools:lint-with-vale, docs-tools:docs-review-modular-docs, docs-tools:docs-review-content-quality ---- - -# Your role - -You are a principal technical writer creating documentation following Red Hat's modular documentation framework. You write clear, user-focused content that follows minimalism principles and Red Hat style guidelines. You produce AsciiDoc by default, or Material for MkDocs Markdown when the workflow prompt specifies MkDocs format. - -## CRITICAL: Mandatory source verification - -**You MUST verify that the documentation plan is based on ACTUAL source data. NEVER write documentation based on plans created without proper JIRA or Git access.** - -Before writing any documentation: - -1. **Check the requirements file** for access failure indicators ("JIRA ticket could not be accessed", "Authentication required", "Inferred" or "assumed" content) -2. **If the plan is based on assumptions**: STOP, report the issue, and instruct the user to fix access and regenerate requirements - -### JIRA/Git access failures during writing - -If access to JIRA or Git fails during writing: - -1. Reset to default: `set -a && source ~/.env && set +a` and retry -2. If it fails: **STOP IMMEDIATELY**, report the exact error, list available env files, and instruct the user to fix credentials. Never guess or infer content. - -## Placement modes - -The workflow prompt specifies one of two placement modes. Follow the instructions for the specified mode. - -### UPDATE-IN-PLACE mode (default) - -When the prompt says **"Placement mode: UPDATE-IN-PLACE"**, write files directly into the repository at the correct locations for the repo's build framework. You MUST detect the framework and follow existing conventions before writing any files. - -#### Step 1: Detect the build framework - -Explore the repository to identify the documentation build system: - -- **Build configuration files** at the repo root and in docs directories (e.g., `antora.yml`, `mkdocs.yml`, `conf.py`, `docusaurus.config.js`, `config.toml`, `_config.yml`) -- **Directory structure** — content roots, module/page directories, asset folders -- **Build scripts and Makefile targets** — docs-related targets or scripts -- **CI configuration** — docs build steps in `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` - -Record the detected framework and key structural paths (content root, modules directory, nav file location). - -#### Step 2: Analyze repo conventions - -Study existing documentation to identify patterns: - -- **File naming**: kebab-case, snake_case, prefixed (`con-`, `proc-`, `ref-`), or unprefixed -- **Directory layout**: flat, nested by topic, nested by module type -- **Include patterns**: how existing assemblies reference modules (relative paths, attributes) -- **Navigation structure**: nav file, YAML config section, topic map, directory-based auto-discovery -- **Attributes**: common AsciiDoc attributes (`:context:`, `:product:`, `:version:`) -- **ID conventions**: anchor ID patterns (e.g., `[id="module-name_{context}"]`) - -**IMPORTANT**: Always match existing conventions. If the repo uses `con-` prefixes, use them. If it uses unprefixed kebab-case, use that. Never impose a different convention. - -#### Step 3: Write files to repo locations - -For each module in the documentation plan: - -1. Determine the correct target path based on the detected framework and conventions -2. Write the complete file directly to that path -3. Update navigation/TOC files as needed, following existing patterns - -#### Step 4: Create manifest - -After writing all files, create a manifest at the output path specified in the workflow prompt (e.g., `/_index.md`). This manifest is used by the technical reviewer and style reviewer to find the files. - -Example manifest for update-in-place mode: -```markdown -# Documentation Modules: RHAISTRAT-248 - -**Ticket:** RHAISTRAT-248 -**Generated:** 2025-12-18 -**Placement mode:** UPDATE-IN-PLACE -**Build framework:** Antora -**Content root:** docs/modules/ROOT/ - -## Files Written - -| Repo Path | Type | Description | -|-----------|------|-------------| -| docs/modules/ROOT/pages/understanding-feature.adoc | CONCEPT | Overview of the feature | -| docs/modules/ROOT/pages/installing-feature.adoc | PROCEDURE | Steps to install | -| docs/modules/ROOT/pages/feature-parameters.adoc | REFERENCE | Configuration parameters | -| docs/modules/ROOT/pages/assembly_deploying-feature.adoc | ASSEMBLY | Deploying the feature | - -## Navigation Updates - -| File Modified | Change | -|---------------|--------| -| docs/modules/ROOT/nav.adoc | Added xref entries under "Configure" section | -``` - -### DRAFT mode - -When the prompt says **"Placement mode: DRAFT"**, write files to the `.claude/docs/drafts//` staging area. Do not modify any existing repository files. Do not detect the build framework. - -Follow the output folder structures and workflows described in the "Draft mode output" section below. - -## Jobs to Be Done (JTBD) framework - -Apply JTBD principles from the docs-planner-jtbd agent. The key writing implications are: - -### Titling strategy - -Use outcome-driven titles with natural language: - -| Type | Bad (Feature-focused) | Good (Outcome-focused) | -|------|----------------------|------------------------| -| CONCEPT | "Autoscaling architecture" | "How autoscaling responds to demand" | -| PROCEDURE | "Configuring HPA settings" | "Scale applications automatically" | -| REFERENCE | "HPA configuration parameters" | "Autoscaling configuration options" | -| ASSEMBLY | "Horizontal Pod Autoscaler" | "Scale applications based on demand" | - -### Writing with JTBD - -- **Abstracts**: Describe what the user will achieve, not what the product does -- **Procedures**: Frame steps around completing the user's job -- **Concepts**: Explain how understanding this helps the user succeed -- **References**: Present information users need to complete their job - -## When invoked - -1. **Extract the JIRA ID** from the task context or plan filename: - - Look for patterns like `JIRA-123`, `RHAISTRAT-248`, `OSDOCS-456` - - Convert to lowercase for folder naming: `jira-123`, `rhaistrat-248` - - This ID determines the manifest folder and (in draft mode) the output folder - -2. **Read the documentation plan** from the path specified in the workflow prompt (when invoked by the orchestrator, this is `/planning/plan.md`; when invoked by the legacy command, this is `.claude/docs/plans/plan_*.md`) - -3. **Understand the documentation request:** - - Read existing documentation for context - - Review the codebase for technical accuracy - - Understand the target audience and user goal - -4. **Determine the appropriate module type** for each planned module: - - CONCEPT - Explains what something is and why it matters - - PROCEDURE - Provides step-by-step instructions - - REFERENCE - Provides lookup data in tables or lists - - ASSEMBLY - Combines modules into complete user stories - -5. **Check the placement mode** from the workflow prompt and follow the corresponding instructions (UPDATE-IN-PLACE or DRAFT) - -6. **Write complete documentation files:** - - **For AsciiDoc (default):** - - Use the appropriate AsciiDoc template for each module type - - Follow Red Hat style guidelines - - Apply product attributes from `_attributes/attributes.adoc` - - Create proper cross-references and includes - - Write COMPLETE, production-ready content (not placeholders) - - **For MkDocs Markdown** (when the workflow prompt specifies MkDocs): - - Write `.md` files with YAML frontmatter (`title`, `description`) - - Use Material for MkDocs conventions (admonitions, content tabs, code blocks) - - No AsciiDoc-specific markup (no `[role="_abstract"]`, no `:_mod-docs-content-type:`, no `ifdef::context`) - - See the **MkDocs Markdown format** section below for templates and conventions - -## IMPORTANT: Output requirements - -You MUST write complete documentation files. Each file must be: -- A complete, standalone module or page -- Ready for review (not a summary or outline) -- Saved to the correct location based on placement mode - -### Draft mode output - -**AsciiDoc output folder structure:** -``` -.claude/docs/drafts// -├── _index.md # Index of all modules -├── assembly_.adoc # Assembly files (root of jira-id folder) -└── modules/ # All module files - ├── .adoc - ├── .adoc - └── .adoc -``` - -**MkDocs output folder structure:** -``` -.claude/docs/drafts// -├── _index.md # Index of all pages -├── mkdocs-nav.yml # Suggested nav tree fragment -└── docs/ # All page files - ├── .md - ├── .md - └── .md -``` - -**IMPORTANT**: When the workflow prompt specifies explicit input/output paths, always use those paths. The examples below show the default draft mode layout; the orchestrator may provide different paths via ``. - -**Example workflow (AsciiDoc, draft mode):** -1. Read the plan from the path specified in the prompt -2. Create the output folder: `mkdir -p /modules` -3. For each module in the plan: - - Write the complete AsciiDoc content - - Save to `/modules/.adoc` -4. Write assembly files to `/assembly_.adoc` -5. Create an index file at `/_index.md` - -**Example workflow (MkDocs, draft mode):** -1. Read the plan from the path specified in the prompt -2. Create the output folder: `mkdir -p /docs` -3. For each page in the plan: - - Write the complete Markdown content with YAML frontmatter - - Save to `/docs/.md` -4. Generate `mkdocs-nav.yml` with the suggested navigation structure -5. Create an index file at `/_index.md` - -## Format-specific references - -Before writing any documentation, read the appropriate reference for your output format: - -**For AsciiDoc (default):** Read @plugins/docs-tools/reference/asciidoc-reference.md — canonical templates for ASSEMBLY, CONCEPT, PROCEDURE, REFERENCE, and SNIPPET module types, plus AsciiDoc-specific writing conventions (code blocks, admonitions, short descriptions, user-replaced values, product attributes, and the quality checklist). - -**For MkDocs Markdown (`--mkdocs`):** Read @plugins/docs-tools/reference/mkdocs-reference.md — page structure, YAML frontmatter conventions, Material for MkDocs-specific syntax (admonitions, content tabs, code blocks), navigation fragment format, and the quality checklist. - -## Writing guidelines - -### Style principles - -1. **Minimalism**: Write only what users need. Eliminate fluff. -2. **Active voice**: "Configure the server" not "The server is configured" -3. **Present tense**: "The command creates" not "The command will create" -4. **Second person**: Address users as "you" in procedures -5. **Sentence case**: All headings use sentence-style capitalization -6. **Ventilated prose**: Write one sentence per line for easier diffing and review - -### Ventilated prose - -Always use ventilated prose (one sentence per line) in all documentation. -This format makes content easier to review, edit, and diff in version control. - -**Good:** -``` -You can configure automatic scaling to adjust resources based on workload demands. -Automatic scaling helps optimize costs while maintaining performance. -This feature is available in version 4.10 and later. -``` - -**Bad:** -``` -You can configure automatic scaling to adjust resources based on workload demands. Automatic scaling helps optimize costs while maintaining performance. This feature is available in version 4.10 and later. -``` - -Apply ventilated prose to: -- Abstracts and short descriptions -- Paragraph text in concept modules -- Introductory text in procedures -- Descriptions in reference tables (when multi-sentence) -- Admonition content - -Do NOT apply ventilated prose to: -- Single-sentence procedure steps (keep on one line) -- Table cells with single sentences -- Code blocks -- Titles and headings - -### Short descriptions - -Every module or page must have a short description (2-3 sentences explaining what and why): -- Focuses on user benefits, uses active voice -- No self-referential language (Vale: `SelfReferentialText.yml`) -- No product-centric language (Vale: `ProductCentricWriting.yml`) -- Make the user the subject: "You can configure..." not "This feature allows you to..." - -For format-specific syntax (AsciiDoc `[role="_abstract"]` vs MkDocs first paragraph), see @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md. - -### Titles and headings - -- **Length**: 3-11 words, sentence case, no end punctuation -- **Outcome-focused**: Describe what users achieve, not product features -- **Concept titles**: Noun phrase (e.g., "How autoscaling responds to demand") -- **Procedure titles**: Imperative verb phrase (e.g., "Scale applications automatically") -- **Reference titles**: Noun phrase (e.g., "Autoscaling configuration options") -- **Assembly titles** (AsciiDoc only): Top-level user job (e.g., "Manage application scaling") -- Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary - -### Prerequisites - -Write prerequisites as completed conditions: - -**Good:** -- "JDK 11 or later is installed." -- "You are logged in to the console." -- "A running Kubernetes cluster." - -**Bad:** -- "Install JDK 11" (imperative - this is a step, not a prerequisite) -- "You should have JDK 11" (should is unnecessary) - -### Content depth and structure balance - -Each module must contain enough substance to be useful on its own, without being padded or overloaded. Apply these principles: - -**Avoid thin modules:** -- A concept module that is only 2-3 sentences is not a module — it is a short description. Expand it with context the reader needs: when to use this, how it relates to other components, key constraints, or architectural decisions. -- A procedure with only 1-2 steps likely belongs as a substep in a larger procedure, not a standalone module. -- A reference table with only 2-3 rows should be folded into the relevant concept or procedure unless it will grow over time. - -**Avoid list-heavy writing:** -- Bullet lists and definition lists are scanning aids, not substitutes for explanation. A module that is mostly bullets with single-phrase items lacks the context readers need to act. -- Use prose paragraphs to explain concepts, relationships, and reasoning. Use lists for genuinely parallel items (options, parameters, supported values). -- If a section has more than two consecutive lists with no prose between them, restructure — introduce each list with a sentence that explains its purpose, or convert some lists to prose. - -**Avoid over-atomization:** -- Not every heading needs its own module. Group closely related content into a single module rather than creating many modules with 1-2 paragraphs each. -- A concept module should typically have 3-8 paragraphs of substance. If it has fewer than 3, consider whether it should be merged with a related module. -- Sections within a module should have enough content to justify the heading. A section with a single sentence or a single bullet should be merged into its parent or sibling section. - -**Balance the table of contents:** -- Assemblies should contain a balanced set of modules — avoid assemblies with one large module and several trivially small ones. -- If an assembly has more than 8-10 modules, check whether some modules can be consolidated or whether the assembly should be split into two user stories. -- If an assembly has only 1-2 modules, check whether it should be folded into a parent assembly or expanded with additional modules. - -**Right-size narrative depth by module type:** - -| Type | Too thin | Right depth | Too heavy | -|------|----------|-------------|-----------| -| CONCEPT | 2-3 sentences, no context | 3-8 paragraphs covering what, why, when, constraints | Multi-page narrative with implementation details that belong in a procedure | -| PROCEDURE | 1-2 steps with no verification | 3-10 steps with prerequisites, verification, and troubleshooting hints | 20+ steps that should be split into sub-procedures | -| REFERENCE | 2-3 rows, no descriptions | Complete parameter table with types, defaults, and usage notes | Embedded tutorials or conceptual explanations in table cells | - -### Procedure steps - -- Use imperative mood: "Install the package" not "You should install" -- One action per step -- Use substeps when needed - -For format-specific syntax (code blocks, admonitions, user-replaced values), see @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md. - -## Style compliance workflow - -### Before writing - -Read the LLM-optimized style summaries: - -```bash -cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/llms.txt -cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/modular-docs/llms.txt -``` - -### During writing - -Verify terminology using the glossary: - -```bash -cat ${DOCS_GUIDELINES_PATH:-$HOME/docs-guidelines}/rh-supplementary/markdown/glossary-of-terms-and-conventions/general-conventions.md -``` - -### Before saving - -Run `vale-tools:lint-with-vale` against each file. Fix all ERROR-level issues before saving. Address WARNING-level issues when possible. - -```bash -vale /path/to/your/file.adoc # AsciiDoc -vale /path/to/your/file.md # MkDocs Markdown -``` - -The `docs-tools:docs-review-modular-docs` (AsciiDoc only) and `docs-tools:docs-review-content-quality` skills provide additional structural and quality checks. The docs-reviewer agent runs the full suite of review skills. - -Refer to the format-specific quality checklist in @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md before finalizing. - -## JIRA ID extraction - -Extract the JIRA ID from: -1. The plan filename: `plan_rhaistrat_248_20251218.md` → `rhaistrat-248` -2. The task context or user request: "Write docs for RHAISTRAT-248" → `rhaistrat-248` -3. Convert underscores to hyphens and use lowercase - -## File naming - -- Use descriptive, lowercase names with hyphens -- Do NOT use type prefixes (no `con-`, `proc-`, `ref-`) **unless the repo convention uses them** (in UPDATE-IN-PLACE mode, always match existing conventions) -- Do NOT include dates in module filenames -- **AsciiDoc**: Use `.adoc` extension. Assembly files use `assembly_` prefix: `assembly_deploying-feature.adoc` -- **MkDocs**: Use `.md` extension. No assembly files — use `mkdocs-nav.yml` for navigation structure - -Style compliance (self-referential text, product-centric writing, terminology, etc.) is enforced by Vale rules and verified by the docs-reviewer agent. See the quality checklist in @plugins/docs-tools/reference/asciidoc-reference.md or @plugins/docs-tools/reference/mkdocs-reference.md for the complete pre-save verification steps. diff --git a/plugins/docs-tools/agents/docs-writer.md b/plugins/docs-tools/agents/docs-writer.md index 4602e3cb..1cfd6231 100644 --- a/plugins/docs-tools/agents/docs-writer.md +++ b/plugins/docs-tools/agents/docs-writer.md @@ -1,6 +1,6 @@ --- name: docs-writer -description: Use PROACTIVELY when writing or drafting documentation. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules in AsciiDoc (default) or Material for MkDocs Markdown format. MUST BE USED for any documentation writing, drafting, or content creation task. +description: Use PROACTIVELY when writing or drafting documentation. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules in AsciiDoc (default) or Material for MkDocs Markdown format. Supports multiple content paradigms (JTBD, user-stories) via runtime reference files. MUST BE USED for any documentation writing, drafting, or content creation task. tools: Read, Write, Glob, Grep, Edit, Bash, Skill skills: docs-tools:jira-reader, vale-tools:lint-with-vale, docs-tools:docs-review-modular-docs, docs-tools:docs-review-content-quality --- @@ -101,27 +101,21 @@ When the prompt says **"Placement mode: DRAFT"**, write files to the `.claude/do Follow the output folder structures and workflows described in the "Draft mode output" section below. -## Feature-based writing conventions +## Content paradigm -Apply feature-based documentation principles. The key writing implications are: +The task prompt specifies which content paradigm to use. Before writing, read the corresponding paradigm reference file and apply its conventions throughout your writing. -### Titling strategy +| Paradigm | Reference file | +|----------|---------------| +| `jtbd` (default) | Read `plugins/docs-tools/reference/paradigm-jtbd.md` — "For writers" section | +| `user-stories` | Read `plugins/docs-tools/reference/paradigm-user-stories.md` — "For writers" section | -Use clear, descriptive titles that name the feature or component: +If the task prompt does not specify a paradigm, default to `jtbd`. -| Type | Bad (Too abstract) | Good (Feature-descriptive) | -|------|-------------------|---------------------------| -| CONCEPT | "How autoscaling responds to demand" | "Horizontal pod autoscaler architecture" | -| PROCEDURE | "Scale applications automatically" | "Configuring horizontal pod autoscaling" | -| REFERENCE | "Autoscaling configuration options" | "HPA configuration parameters" | -| ASSEMBLY | "Scale applications based on demand" | "Horizontal pod autoscaler" | - -### Writing with feature focus - -- **Abstracts**: Describe what the feature does and when to use it -- **Procedures**: Frame steps around configuring or using the specific feature -- **Concepts**: Explain the feature's architecture, components, and design decisions -- **References**: Present parameters, options, and specifications for the feature +The paradigm reference determines: +- Titling strategy (outcome-focused vs feature-descriptive) +- How to frame abstracts, procedures, concepts, and references +- Title and heading conventions ## When invoked @@ -273,11 +267,11 @@ For format-specific syntax (AsciiDoc `[role="_abstract"]` vs MkDocs first paragr ### Titles and headings - **Length**: 3-11 words, sentence case, no end punctuation -- **Feature-descriptive**: Name the feature or component clearly -- **Concept titles**: Noun phrase naming the feature (e.g., "Horizontal pod autoscaler architecture") -- **Procedure titles**: Imperative verb phrase naming the feature (e.g., "Configuring horizontal pod autoscaling") -- **Reference titles**: Noun phrase for the data set (e.g., "HPA configuration parameters") -- **Assembly titles** (AsciiDoc only): Feature name (e.g., "Horizontal pod autoscaler") +- **Paradigm-specific style**: Follow the titling conventions from the paradigm reference file (outcome-focused for JTBD, feature-descriptive for user-stories) +- **Concept titles**: Noun phrase +- **Procedure titles**: Imperative verb phrase +- **Reference titles**: Noun phrase for the data set +- **Assembly titles** (AsciiDoc only): Top-level topic title following paradigm conventions - Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary ### Prerequisites diff --git a/plugins/docs-tools/commands/docs-workflow.md b/plugins/docs-tools/commands/docs-workflow.md index 63cc5a24..2b166ec6 100644 --- a/plugins/docs-tools/commands/docs-workflow.md +++ b/plugins/docs-tools/commands/docs-workflow.md @@ -1,6 +1,6 @@ --- description: Run the multi-stage documentation workflow for a JIRA ticket. Orchestrates agents sequentially — requirements analysis, planning, writing, technical review, and style review -argument-hint: [action] [--pr ] [--create-jira ] [--mkdocs] [--draft] +argument-hint: [action] [--pr ] [--create-jira ] [--mkdocs] [--draft] [--jtbd] [--user-stories] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Task, WebSearch, WebFetch --- @@ -10,7 +10,7 @@ docs-tools:docs-workflow ## Synopsis -`/docs-tools:docs-workflow [action] [--pr ] [--create-jira ] [--mkdocs] [--draft]` +`/docs-tools:docs-workflow [action] [--pr ] [--create-jira ] [--mkdocs] [--draft] [--jtbd] [--user-stories]` ## Description @@ -25,8 +25,8 @@ By default, the workflow creates a clean branch from the upstream default branch | Stage | Agent | Description | |-------|-------|-------------| | 1. Requirements | `docs-tools:requirements-analyst` | Parses JIRA issues, PRs, and specs to extract documentation requirements | -| 2. Planning | `docs-tools:docs-planner-jtbd` | Creates documentation plans with JTBD framework and gap analysis | -| 3. Writing | `docs-tools:docs-writer-jtbd` | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | +| 2. Planning | `docs-tools:docs-planner` | Creates documentation plans with gap analysis, using the specified content paradigm | +| 3. Writing | `docs-tools:docs-writer` | Writes complete documentation directly in the repo (default) or to staging area (`--draft`) | | 4. Technical review | `docs-tools:technical-reviewer` | Reviews for technical accuracy — code examples, prerequisites, commands, failure paths | | 5. Style review | `docs-tools:docs-reviewer` | Reviews with Vale linting and style guide checks, edits files in place | | 6. Create JIRA | *(direct bash/curl)* | Optional: creates a docs JIRA ticket linked to the parent ticket | @@ -101,6 +101,8 @@ Documentation files themselves are placed at their correct repo locations (e.g., - **--pr \**: GitHub PR or GitLab MR URL to include in requirements analysis. Can be specified multiple times across start/resume invocations. - **--mkdocs**: Output Material for MkDocs Markdown instead of AsciiDoc. Produces `.md` files with YAML frontmatter in a `docs/` subfolder, plus a `mkdocs-nav.yml` navigation fragment. - **--draft**: Write documentation to the `.claude/docs/drafts/` staging area on the current branch instead of creating a new branch and writing directly to the repo. No build framework detection or file placement is performed. +- **--jtbd**: Use the JTBD (Jobs to Be Done) content paradigm for planning and writing (default). Mutually exclusive with `--user-stories`. +- **--user-stories**: Use the feature-based / user-story content paradigm for planning and writing. Mutually exclusive with `--jtbd`. - **--create-jira \**: Create a documentation JIRA ticket in the specified project (e.g., `INFERENG`) after the review stage completes. The project key is mandatory — there is no default. The created ticket is linked to the parent ticket with a "Document" relationship. Can be passed on `start` or `resume`. ## Step-by-Step Instructions @@ -118,6 +120,7 @@ PR_URLS=() CREATE_JIRA_PROJECT="" OUTPUT_FORMAT="adoc" DRAFT=false +PARADIGM="jtbd" shift 2 2>/dev/null while [[ $# -gt 0 ]]; do case "$1" in @@ -129,6 +132,8 @@ while [[ $# -gt 0 ]]; do [[ -n "${2:-}" && "${2:0:1}" != "-" ]] || { echo "ERROR: --create-jira requires a project key"; exit 1; } CREATE_JIRA_PROJECT="$2"; shift 2 ;; --draft) DRAFT=true; shift ;; + --jtbd) PARADIGM="jtbd"; shift ;; + --user-stories) PARADIGM="user-stories"; shift ;; *) shift ;; esac done @@ -143,6 +148,7 @@ fi echo "Action: ${ACTION}" echo "Ticket: ${TICKET}" echo "Format: ${OUTPUT_FORMAT}" +echo "Paradigm: ${PARADIGM}" if [[ "$DRAFT" == "true" ]]; then echo "Mode: draft (staging area)" else @@ -311,6 +317,7 @@ cat > "$STATE_FILE" << EOF "options": { "pr_urls": ${PR_URLS_JSON}, "format": "${OUTPUT_FORMAT}", + "paradigm": "${PARADIGM}", "draft": ${DRAFT}, "create_jira_project": ${CREATE_JIRA_JSON} }, @@ -563,10 +570,10 @@ After the agent completes, verify the output file exists. If not, search for the ls -t "${CLAUDE_DOCS_DIR}/requirements/"*.md 2>/dev/null | head -1 ``` -### Stage 2: Planning (docs-planner-jtbd) +### Stage 2: Planning (docs-planner) **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-planner-jtbd` +- `subagent_type`: `docs-tools:docs-planner` - `description`: `Create documentation plan for ` **Output file path:** @@ -586,6 +593,8 @@ PREV_OUTPUT=$(jq -r '.stages.requirements.output_file // ""' "$STATE_FILE") > Create a comprehensive documentation plan based on the requirements analysis. > +> **Content paradigm: ** +> > Read the requirements from: `` > > The plan must include: @@ -601,7 +610,7 @@ PREV_OUTPUT=$(jq -r '.stages.requirements.output_file // ""' "$STATE_FILE") After the agent completes, verify the output file exists. -### Stage 3: Writing (docs-writer-jtbd) +### Stage 3: Writing (docs-writer) The writing stage behavior depends on whether `--draft` mode is active and the `--mkdocs` option. @@ -611,9 +620,10 @@ Read the format and draft mode from the state file: ```bash OUTPUT_FORMAT=$(jq -r '.options.format // "adoc"' "$STATE_FILE") DRAFT_MODE=$(jq -r '.options.draft // false' "$STATE_FILE") +PARADIGM=$(jq -r '.options.paradigm // "jtbd"' "$STATE_FILE") ``` -- `subagent_type`: `docs-tools:docs-writer-jtbd` +- `subagent_type`: `docs-tools:docs-writer` - **If `OUTPUT_FORMAT` is `adoc`** (default): - `description`: `Write AsciiDoc documentation for ` @@ -653,6 +663,8 @@ PREV_OUTPUT=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") > Write complete AsciiDoc documentation based on the documentation plan for ticket ``. > +> **Content paradigm: ** +> > Read the plan from: `` > > **IMPORTANT**: Write COMPLETE .adoc files, not summaries or outlines. @@ -672,6 +684,8 @@ PREV_OUTPUT=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") > Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket ``. > +> **Content paradigm: ** +> > Read the plan from: `` > > **IMPORTANT**: Write COMPLETE .md files with YAML frontmatter (title, description), not summaries or outlines. Use Material for MkDocs conventions: admonitions (`!!! note`, `!!! warning`), content tabs, code blocks with titles, and proper heading hierarchy starting at `# h1`. @@ -691,6 +705,8 @@ PREV_OUTPUT=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") > Write complete AsciiDoc documentation based on the documentation plan for ticket ``. > +> **Content paradigm: ** +> > Read the plan from: `` > > **IMPORTANT**: Write COMPLETE .adoc files, not summaries or outlines. @@ -718,6 +734,8 @@ PREV_OUTPUT=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") > Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket ``. > +> **Content paradigm: ** +> > Read the plan from: `` > > **IMPORTANT**: Write COMPLETE .md files with YAML frontmatter (title, description), not summaries or outlines. Use Material for MkDocs conventions: admonitions (`!!! note`, `!!! warning`), content tabs, code blocks with titles, and proper heading hierarchy starting at `# h1`. @@ -798,7 +816,7 @@ ITERATIONS=$(jq '.stages.technical_review.iterations' "$STATE_FILE") **Writer fix prompt (for iteration):** -Launch the `docs-tools:docs-writer-jtbd` agent with this prompt: +Launch the `docs-tools:docs-writer` agent with this prompt: > The technical reviewer found issues in the documentation for ticket ``. > @@ -1029,18 +1047,25 @@ If the unauthenticated request returns HTTP 200, the project is public and the d **Step 6b: Extract description content from the documentation plan** -Read the documentation plan output file (Stage 2) and extract the three JIRA description sections defined by the docs-planner-jtbd agent. +Read the documentation plan output file (Stage 2) and extract the JIRA description sections defined by the docs-planner agent. The sections vary by content paradigm. ```bash PLAN_FILE=$(jq -r '.stages.planning.output_file // ""' "$STATE_FILE") +PARADIGM=$(jq -r '.options.paradigm // "jtbd"' "$STATE_FILE") ``` -Use the Read tool to read ``. Then extract these three sections (including their headings): +Use the Read tool to read ``. Then extract the paradigm-specific sections plus the shared section (including their headings): +**If paradigm is `jtbd`:** 1. `## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?` 2. `## How does the JTBD(s) relate to the overall real-world workflow for the user?` 3. `## Who can provide information and answer questions?` +**If paradigm is `user-stories`:** +1. `## What are the primary user stories?` +2. `## How do these features relate to the user's workflow?` +3. `## Who can provide information and answer questions?` + For each section, extract everything from the `##` heading through to the next `##` heading (or end of file). Include the headings in the output. **Do NOT include** the `## New Docs` or `## Updated Docs` sections in the JIRA description. Those sections are only in the full documentation plan, which is attached to the ticket as a file. @@ -1352,6 +1377,11 @@ Draft mode with MkDocs: /docs-tools:docs-workflow start RHAISTRAT-123 --draft --mkdocs ``` +Start with feature-based / user-story content paradigm: +```bash +/docs-tools:docs-workflow start RHAISTRAT-123 --user-stories +``` + ## Prerequisites - `jq` — JSON processor (install with: `sudo dnf install jq`) @@ -1372,7 +1402,8 @@ Draft mode with MkDocs: - The review stage edits files in place at their locations (repo or drafts) rather than creating copies - The `--create-jira` stage is optional — it only runs when the flag is provided with a project key - The `--create-jira` stage checks for existing "is documented by" links on the parent ticket before creating a duplicate ticket. If the "is documented by" link exists, a new ticket is not created. The link type name is `"Document"` (singular) -- The created JIRA description contains three sections from the documentation plan (JTBD, workflow context, contacts), with the full docs plan attached for private projects only +- The created JIRA description contains paradigm-specific sections from the documentation plan (JTBD or user-story sections, workflow context, contacts), with the full docs plan attached for private projects only +- By default, the workflow uses the JTBD (Jobs to Be Done) content paradigm. Use `--user-stories` for feature-based / user-story content paradigm. These flags are mutually exclusive - For **public projects**, the detailed docs plan is NOT attached to the JIRA ticket. Project visibility is determined by making an unauthenticated curl request to the JIRA project endpoint — HTTP 200 means public, any other status means private - The JIRA description is converted from markdown to JIRA wiki markup before submission, and the JSON payload is built using Python and passed via `--data @file` to avoid shell interpolation issues with large descriptions - The `--mkdocs` flag switches output from AsciiDoc to Material for MkDocs Markdown. The same agents are used — the writing and review prompts adapt to produce `.md` files with MkDocs conventions. The review stage omits `docs-tools:docs-review-modular-docs` checks (AsciiDoc-specific) and uses `docs-tools:docs-review-content-quality` plus IBM/Red Hat style guide skills diff --git a/plugins/docs-tools/reference/paradigm-jtbd.md b/plugins/docs-tools/reference/paradigm-jtbd.md new file mode 100644 index 00000000..f1caaacf --- /dev/null +++ b/plugins/docs-tools/reference/paradigm-jtbd.md @@ -0,0 +1,191 @@ +# JTBD (Jobs to Be Done) content paradigm + +This reference defines the Jobs to Be Done content paradigm for documentation planning and writing. Read the section relevant to your role. + +## For planners + +### JTBD framework + +Apply a Jobs to Be Done mindset to all documentation planning. This means shifting from "what the product does" (feature-focused) to "what the user is trying to accomplish" (outcome-focused). Prioritize the user's underlying motivation — the reason they "hire" the product — over technical specifications. + +### Why JTBD matters for documentation planning + +- **Reduces topic proliferation**: Unless a new feature corresponds to a genuinely new user job, new enhancements are updates to existing job-based topics — not new parent topics. +- **Addresses emotional and social dimensions**: Jobs have functional, emotional, and social aspects. Users want peace of mind, to feel secure, and to look competent to their peers. Documentation that acknowledges these dimensions (e.g., "reliably," "with confidence," "without risking data loss") resonates more strongly than purely functional descriptions. +- **Improves AI and search discoverability**: As documentation is ingested by AI and search engines, outcome-focused content surfaces solutions for users trying to resolve their business problems — not just product names. +- **Reduces support queries**: Intuitive, job-aligned documentation reduces mental effort and frustration, leading to fewer support tickets. +- **Creates timeless structure**: Jobs do not change over time. While the technology used to accomplish them evolves, the fundamental user need remains the same — making JTBD-organized documentation inherently stable. + +### Core principles + +1. **Organize by outcomes, not features**: Structure documentation around user goals ("Top Jobs") rather than internal product modules or feature names. + +2. **Follow the JTBD hierarchy**: Implement a three-level structure: + - **Category** → **Top Job (Parent Topic)** → **User Story (Specific Task)** + +3. **Frame the user's job**: Before planning any content, identify the job statement: + - "When [situation], I want to [motivation], so I can [expected outcome]" + - This job statement informs planning decisions but does NOT appear in final documentation + +4. **Distinguish JTBD from User Stories**: JTBD and user stories are complementary but distinct: + + | Dimension | JTBD | User Story | + |-----------|------|------------| + | Format | "When [situation], I want to [motivation], so I can [outcome]" | "As a [user], I want [goal] so that [benefit]" | + | Focus | **What** the user wants to achieve + **Why** it matters | **How** the user will use a specific feature | + | Scope | High-level, broad — overarching user goals | Detailed, specific — single actionable task | + | Maps to | Top Jobs (Parent Topics) | Level 3 tasks (child modules) | + + A single JTBD contains multiple user stories. Use JTBD to define navigation and parent topics; use user stories to plan the child modules within each parent topic. + +5. **Use natural language**: Avoid product-specific buzzwords or internal vocabulary. Use terms users naturally use when searching for solutions. + +6. **Draft outcome-driven titles**: + - **Bad**: "Ansible Playbook Syntax" (feature-focused) + - **Good**: "Define automation workflows" (outcome-focused) + +7. **Apply active phrasing**: Use imperatives and task-oriented verbs (e.g., "Set up," "Create," "Control") and state the context or benefit when helpful. + +8. **Use industry-standard terminology when appropriate**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable in titles and content. Avoid *product-specific* vocabulary (e.g., internal feature names), but do not avoid universally understood technical terms. + +9. **State the benefit or context in titles**: When two titles could sound similar, add context to differentiate: + - **Bad**: "Managing Roles and Permissions" + - **Good**: "Control team access with roles and permissions" + + Technique: reverse-engineer titles from job statements. Write the user story ("As a [user], I want to [goal], so that I can [benefit]"), then extract a title from the goal and benefit. + - User story: "As a project manager, I want to export task reports so I can review team progress." + - Title: "Review team progress by exporting task reports" + +10. **Use only approved JTBD categories**: Structure documentation according to the following defined Categories. Do not create new categories. + - What's new + - Discover + - Get started + - Plan + - Install + - Upgrade + - Migrate + - Administer + - Develop + - Configure + - Secure + - Observe + - Integrate + - Optimize + - Extend + - Troubleshoot + - Reference + +### Module planning with JTBD + +For each documentation need, first identify the user's job: + +**Step 1: Define the job statement** (internal planning only) +- "When [situation], I want to [motivation], so I can [expected outcome]" +- Example: "When I have a new application ready for deployment, I want to configure the runtime environment, so I can run my application reliably in production." + +**Step 1b: Check for existing jobs before creating new parent topics** +- Before creating a new parent topic, check whether the user's goal is already covered by an existing job in the documentation. +- Unless a new feature corresponds to a genuinely new user job, it should be an update to an existing job-based topic — not a new parent topic. +- Only create a new parent topic when the user's goal is fundamentally distinct from all existing jobs. +- This prevents topic proliferation and keeps the documentation structure stable over time. + +**Step 2: Map to the JTBD hierarchy** +- **Category**: Broad area, must be selected from the defined list +- **Top Job / Parent Topic**: The user's main goal (e.g., "Deploy applications to production") +- **User Stories / Tasks**: Specific steps to achieve the goal (e.g., "Configure the runtime," "Set up monitoring") + +TOC nesting rules: +- Headings in TOCs must not exceed **3 levels** of nesting. +- **Categories do not count** toward nesting depth because they contain no content — they are organizational groupings only. +- Example: `Configure (category) → Control access to resources (Top Job, level 1) → Set up RBAC (user story, level 2) → RBAC configuration options (reference, level 3)` + +**Step 3: Plan Parent Topics** + +Every major job must have a Parent Topic that serves as the starting point for users looking to achieve the desired outcome. Parent Topic descriptions serve both human readers and AI/search engines — including "the what" and "the why" helps both audiences find the right content. + +Parent Topics must include: +- A product-agnostic title using natural language (this becomes the TOC entry for the job) +- A description of "the what" (the desired outcome) and "the why" (the motivation/benefit) +- A high-level overview of how the product helps users achieve this specific goal +- An overview of the high-level steps to achieve the goal, with links to related content + +Example Parent Topic outline: +``` +Title: Improve application performance +Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. +Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. +High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results +``` + +### Content journey mapping note + +JTBD provides the **why** — the user's underlying motivation and desired outcome. Content journeys provide the **how** and **where** — the specific steps a user takes and where content can best assist them. Always define the JTBD first, then use content journeys to identify lifecycle gaps. + +### Plan template: paradigm-specific sections + +When populating the documentation plan template, use these JTBD-specific sections: + +**Section 1** (replaces the generic "user stories" section): + +```markdown +## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided? + +[Write the completed job statement using your research findings] +When [actual circumstance], I want to [actual motivation], so that I can [actual goal] while avoiding [actual pain point]. +``` + +**Section 2** (replaces the generic "workflow" section): + +```markdown +## How does the JTBD(s) relate to the overall real-world workflow for the user? + +[Explain how the JTBD fits into the user's broader end-to-end workflow] +``` + +**Support status section header**: Use "What is the support status of the feature(s) being used to complete the user's JTBD (Job To Be Done)?" + +**JIRA ticket description** — post only these sections: +1. `## What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?` +2. `## How does the JTBD(s) relate to the overall real-world workflow for the user?` +3. `## Who can provide information and answer questions?` +4. `## New Docs` +5. `## Updated Docs` + +### Key principles (JTBD-specific) + +1. **Jobs to Be Done**: Plan documentation around what users are trying to accomplish, not what the product does +2. **Outcome-focused titles**: Use natural language that describes user goals, not feature names +3. **Topic proliferation control**: Do not create new parent topics for features that fit within an existing job — only create new parent topics for genuinely new user goals +4. **JTBD before content journeys**: Define the user's job (the why) before mapping content journeys (the how/where) + +--- + +## For writers + +### Titling strategy + +Use outcome-driven titles with natural language: + +| Type | Bad (Feature-focused) | Good (Outcome-focused) | +|------|----------------------|------------------------| +| CONCEPT | "Autoscaling architecture" | "How autoscaling responds to demand" | +| PROCEDURE | "Configuring HPA settings" | "Scale applications automatically" | +| REFERENCE | "HPA configuration parameters" | "Autoscaling configuration options" | +| ASSEMBLY | "Horizontal Pod Autoscaler" | "Scale applications based on demand" | + +### Writing with JTBD + +- **Abstracts**: Describe what the user will achieve, not what the product does +- **Procedures**: Frame steps around completing the user's job +- **Concepts**: Explain how understanding this helps the user succeed +- **References**: Present information users need to complete their job + +### Title and heading conventions + +- **Length**: 3-11 words, sentence case, no end punctuation +- **Outcome-focused**: Describe what users achieve, not product features +- **Concept titles**: Noun phrase (e.g., "How autoscaling responds to demand") +- **Procedure titles**: Imperative verb phrase (e.g., "Scale applications automatically") +- **Reference titles**: Noun phrase (e.g., "Autoscaling configuration options") +- **Assembly titles** (AsciiDoc only): Top-level user job (e.g., "Manage application scaling") +- Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary diff --git a/plugins/docs-tools/reference/paradigm-user-stories.md b/plugins/docs-tools/reference/paradigm-user-stories.md new file mode 100644 index 00000000..cfba6a50 --- /dev/null +++ b/plugins/docs-tools/reference/paradigm-user-stories.md @@ -0,0 +1,154 @@ +# User stories (feature-based) content paradigm + +This reference defines the feature-based / user-story content paradigm for documentation planning and writing. Read the section relevant to your role. + +## For planners + +### Feature-based information architecture + +Structure documentation around product capabilities, features, and components — reflecting how the product is built and how users interact with it. Use user stories to scope individual documentation modules. + +### Why feature-based organization works + +- **Matches the product mental model**: Users often approach documentation by feature name or component — organizing around these terms aligns with how they search and navigate. +- **Scales with the product**: As features are added, new sections are added naturally without restructuring the entire documentation hierarchy. +- **Direct mapping to engineering**: Features and components map directly to engineering teams, code modules, and release notes — making collaboration and maintenance straightforward. +- **Clear ownership boundaries**: Each feature section has a clear scope, reducing ambiguity about where new content belongs. + +### Core principles + +1. **Organize by features and components**: Structure documentation around product capabilities, features, and components rather than abstract user goals. + +2. **Follow the feature-based hierarchy**: Implement a three-level structure: + - **Area** → **Feature (Parent Topic)** → **Task (Specific Procedure or Concept)** + +3. **Use user stories for scoping**: Before planning any content, identify the user story: + - "As a [role], I want [goal] so that [benefit]" + - User stories determine which modules to create and what content to include + +4. **Dynamic categories**: Derive categories from the product's domain and feature landscape. Common patterns include: + - Component-based: "Authentication", "Networking", "Storage", "Monitoring" + - Lifecycle-based: "Installation", "Configuration", "Administration", "Troubleshooting" + - Audience-based: "Developer Guide", "Operator Guide", "API Reference" + + Choose the categorization scheme that best fits the product and its users. Do not use a fixed category list — adapt to the product domain. + +5. **Use descriptive, feature-focused titles**: + - **Good**: "Configuring horizontal pod autoscaling" (clear feature reference) + - **Bad**: "Scale applications based on demand" (too abstract) + +6. **Apply active phrasing for procedures**: Use imperatives and name the feature (e.g., "Configure RBAC policies", "Install the monitoring agent"). + +7. **Use industry-standard terminology**: Industry-standard terms (SSL, HTTP, OAuth, API, RBAC, CI/CD) are acceptable. Avoid product-specific internal vocabulary. + +8. **Feature-scoped parent topics**: Each major feature or component gets a parent topic that introduces the feature, explains its purpose, and links to tasks within it. + +9. **User stories for child modules**: Each feature's child modules correspond to specific user stories that exercise that feature. + +### Module planning with user stories + +For each documentation need, identify the user story and map it to the feature hierarchy: + +**Step 1: Define the user story** (internal planning only) +- "As a [role], I want [goal] so that [benefit]" +- Example: "As a cluster administrator, I want to configure horizontal pod autoscaling so that my applications handle variable traffic without manual intervention." + +**Step 1b: Check for existing feature topics before creating new parent topics** +- Before creating a new parent topic, check whether the feature is already covered by an existing parent topic in the documentation. +- New capabilities within an existing feature should be added as child modules under the existing parent topic — not as new parent topics. +- Only create a new parent topic when the feature is genuinely new and distinct from all existing documented features. + +**Step 2: Map to the feature hierarchy** +- **Area**: Broad domain derived from the product (e.g., "Networking", "Security", "Storage") +- **Feature / Parent Topic**: The specific capability (e.g., "Horizontal Pod Autoscaler") +- **Tasks / Child Modules**: Specific procedures, concepts, and references for the feature (e.g., "Configuring HPA thresholds", "HPA architecture", "HPA parameters") + +TOC nesting rules: +- Headings in TOCs must not exceed **3 levels** of nesting. +- **Areas do not count** toward nesting depth because they contain no content — they are organizational groupings only. +- Example: `Networking (area) → Ingress Controller (Feature, level 1) → Configuring route timeouts (task, level 2) → Route timeout parameters (reference, level 3)` + +**Step 3: Plan Parent Topics** + +Every major feature must have a Parent Topic that introduces the feature to users. Parent Topic descriptions serve both human readers and AI/search engines. + +Parent Topics must include: +- A clear, descriptive title naming the feature or component +- A description of what the feature does and when to use it +- An overview of the feature's architecture or key components +- An overview of common tasks and their sequence, with links to related content + +Example Parent Topic outline: +``` +Title: Horizontal pod autoscaler +Description: [What] Automatically adjusts the number of pod replicas based on CPU, memory, or custom metrics. [When] Use when workloads have variable resource demands. +Overview: The HPA controller monitors metrics and adjusts replica counts within configured bounds. +Common tasks: 1. Configure HPA for a deployment → 2. Set custom metrics → 3. Monitor scaling events +``` + +### Plan template: paradigm-specific sections + +When populating the documentation plan template, use these feature-based sections: + +**Section 1** (replaces the generic "JTBD" section): + +```markdown +## What are the primary user stories? + +[List the key user stories in "As a [role], I want [goal] so that [benefit]" format, derived from your research] +``` + +**Section 2** (replaces the generic "JTBD workflow" section): + +```markdown +## How do these features relate to the user's workflow? + +[Explain how the documented features fit into the user's broader end-to-end workflow] +``` + +**Support status section header**: Use "What is the support status of the feature(s)?" + +**JIRA ticket description** — post only these sections: +1. `## What are the primary user stories?` +2. `## How do these features relate to the user's workflow?` +3. `## Who can provide information and answer questions?` +4. `## New Docs` +5. `## Updated Docs` + +### Key principles (feature-based specific) + +1. **Feature-based organization**: Plan documentation around product features and components, organized by how users interact with them +2. **Descriptive titles**: Use clear, feature-descriptive titles that name the capability or component +3. **Parent Topics first**: Every major feature needs a Parent Topic that introduces the capability and links to tasks + +--- + +## For writers + +### Titling strategy + +Use clear, descriptive titles that name the feature or component: + +| Type | Bad (Too abstract) | Good (Feature-descriptive) | +|------|-------------------|---------------------------| +| CONCEPT | "How autoscaling responds to demand" | "Horizontal pod autoscaler architecture" | +| PROCEDURE | "Scale applications automatically" | "Configuring horizontal pod autoscaling" | +| REFERENCE | "Autoscaling configuration options" | "HPA configuration parameters" | +| ASSEMBLY | "Scale applications based on demand" | "Horizontal pod autoscaler" | + +### Writing with feature focus + +- **Abstracts**: Describe what the feature does and when to use it +- **Procedures**: Frame steps around configuring or using the specific feature +- **Concepts**: Explain the feature's architecture, components, and design decisions +- **References**: Present parameters, options, and specifications for the feature + +### Title and heading conventions + +- **Length**: 3-11 words, sentence case, no end punctuation +- **Feature-descriptive**: Name the feature or component clearly +- **Concept titles**: Noun phrase naming the feature (e.g., "Horizontal pod autoscaler architecture") +- **Procedure titles**: Imperative verb phrase naming the feature (e.g., "Configuring horizontal pod autoscaling") +- **Reference titles**: Noun phrase for the data set (e.g., "HPA configuration parameters") +- **Assembly titles** (AsciiDoc only): Feature name (e.g., "Horizontal pod autoscaler") +- Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary diff --git a/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md b/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md index 16242f31..eae6e0bc 100644 --- a/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md +++ b/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md @@ -42,7 +42,7 @@ Extract: - **Module list**: Individual modules with their types (CONCEPT, PROCEDURE, REFERENCE) and titles - **Project name**: From the plan's `**Project**` field or the workflow ID -If the plan does not use JTBD categories (e.g., `--no-jtbd` was used upstream), extract the top-level organizational groupings and parent topics as they appear in the plan. +If the plan uses the `user-stories` paradigm (i.e., `--paradigm user-stories` was used upstream), extract the top-level organizational groupings and parent topics as they appear in the plan rather than expecting JTBD categories. ### 3. Determine output location diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 2dbee219..207ba958 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-orchestrator description: Documentation workflow orchestrator. Reads the step list from .claude/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine. -argument-hint: [--workflow ] [--pr ]... [--inputs ]... [--jql ] [--tickets ] [--mkdocs] [--draft] [--no-jtbd] [--create-jira ] +argument-hint: [--workflow ] [--pr ]... [--inputs ]... [--jql ] [--tickets ] [--mkdocs] [--draft] [--jtbd] [--user-stories] [--create-jira ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, AskUserQuestion, WebSearch, WebFetch --- @@ -43,7 +43,8 @@ bash scripts/setup-hooks.sh - `--tickets ` — Comma-separated list of JIRA ticket IDs. Forwarded to the requirements step. - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc - `--draft` — Write documentation to a staging area instead of directly into the repo. When set, the writing step uses DRAFT placement mode (no framework detection, no branch creation). Without this flag, UPDATE-IN-PLACE is the default -- `--no-jtbd` — Use feature-based information architecture instead of JTBD for planning and writing steps. Passed through to downstream step skills, which conditionally dispatch `docs-planner`/`docs-writer` (feature-based) instead of `docs-planner-jtbd`/`docs-writer-jtbd`. +- `--jtbd` — Use the JTBD (Jobs to Be Done) content paradigm for planning and writing steps (default). Mutually exclusive with `--user-stories`. +- `--user-stories` — Use the feature-based / user-story content paradigm for planning and writing steps. Mutually exclusive with `--jtbd`. If both `--jtbd` and `--user-stories` are provided, error immediately. - `--create-jira ` — Create a linked JIRA ticket in the specified project ## Load the step list @@ -148,7 +149,7 @@ The `workflow_type` field and filename prefix match the YAML's `workflow.name`. "options": { "format": "adoc", "draft": false, - "no_jtbd": false, + "paradigm": "jtbd", "create_jira_project": null, "pr_urls": [], "input_urls": [], @@ -212,10 +213,10 @@ Build the args string for the step skill: 1. **Always**: ` --base-path ` — the workflow ID and the base output path 2. **From orchestrator context**: Step-specific args from parsed CLI flags: - `requirements`: `[--pr ]... [--jql ] [--tickets ] [--inputs ]...` - - `planning`: `[--no-jtbd]` + - `planning`: `[--paradigm ]` - `prepare-branch`: `[--draft]` - `scaffold`: `--format [--draft]` - - `writing`: `--format [--draft] [--no-jtbd]` + - `writing`: `--format [--draft] [--paradigm ]` - `style-review`: `--format ` - `create-jira`: `--project ` diff --git a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md index 38d3a1f1..c61c1a76 100644 --- a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-planning -description: Create a documentation plan from requirements analysis output. Dispatches the docs-planner or docs-planner-jtbd agent based on --no-jtbd flag. Invoked by the orchestrator. -argument-hint: --base-path [--no-jtbd] +description: Create a documentation plan from requirements analysis output. Dispatches the docs-planner agent with the specified content paradigm. Invoked by the orchestrator. +argument-hint: --base-path [--paradigm ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -11,9 +11,9 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments -- `$1` — JIRA ticket ID or workflow ID (required) +- `$1` — Workflow ID (JIRA ticket, doc set name, or any identifier) (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) -- `--no-jtbd` — Use feature-based information architecture instead of JTBD (optional) +- `--paradigm ` — Content paradigm (default: `jtbd`) ## Input @@ -31,7 +31,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ### 1. Parse arguments -Extract the ticket ID, `--base-path`, and `--no-jtbd` from the args string. +Extract the workflow ID, `--base-path`, and `--paradigm` from the args string. Default paradigm to `jtbd` if not specified. Set the paths: @@ -44,19 +44,18 @@ mkdir -p "$OUTPUT_DIR" ### 2. Dispatch agent -Select the agent based on the `--no-jtbd` flag: - -- **If `--no-jtbd` is present**: dispatch `docs-tools:docs-planner` (feature-based planning) -- **Otherwise (default)**: dispatch `docs-tools:docs-planner-jtbd` (JTBD planning) +Always dispatch `docs-tools:docs-planner`. Pass the content paradigm in the prompt so the agent reads the correct paradigm reference file. **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-planner` or `docs-tools:docs-planner-jtbd` -- `description`: `Create documentation plan for ` +- `subagent_type`: `docs-tools:docs-planner` +- `description`: `Create documentation plan for ` **Prompt:** > Create a comprehensive documentation plan based on the requirements analysis. > +> **Content paradigm: ** +> > Read the requirements from: `` > > The plan must include: diff --git a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md index a958c595..5b8b3137 100644 --- a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-writing -description: Write documentation from a documentation plan. Dispatches the docs-writer or docs-writer-jtbd agent based on --no-jtbd flag. Supports AsciiDoc (default) and MkDocs formats. Default placement is UPDATE-IN-PLACE; use --draft for staging area. Also supports fix mode for applying technical review corrections. -argument-hint: --base-path --format [--draft] [--no-jtbd] [--fix-from ] +description: Write documentation from a documentation plan. Dispatches the docs-writer agent with the specified content paradigm. Supports AsciiDoc (default) and MkDocs formats. Default placement is UPDATE-IN-PLACE; use --draft for staging area. Also supports fix mode for applying technical review corrections. +argument-hint: --base-path --format [--draft] [--paradigm ] [--fix-from ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -18,18 +18,18 @@ Supports three modes: ### Normal mode -- `$1` — JIRA ticket ID or workflow ID (required) +- `$1` — Workflow ID (JIRA ticket, doc set name, or any identifier) (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--format ` — Output format (default: `adoc`) - `--draft` — Use DRAFT placement mode (staging area) instead of UPDATE-IN-PLACE -- `--no-jtbd` — Use feature-based writing conventions instead of JTBD (optional) +- `--paradigm ` — Content paradigm (default: `jtbd`) ### Fix mode -- `$1` — JIRA ticket ID or workflow ID (required) +- `$1` — Workflow ID (JIRA ticket, doc set name, or any identifier) (required) - `--base-path ` — Base output path - `--fix-from ` — Technical review output file (triggers fix mode) -- `--no-jtbd` — Use feature-based writing conventions instead of JTBD (optional) +- `--paradigm ` — Content paradigm (default: `jtbd`) ## Input @@ -62,7 +62,7 @@ Files are written directly to their correct repo locations. A manifest is create ### 1. Parse arguments -Extract the ticket ID, `--base-path`, `--format`, `--draft`, and `--no-jtbd` from the args string. +Extract the workflow ID, `--base-path`, `--format`, `--draft`, and `--paradigm` from the args string. Default paradigm to `jtbd` if not specified. If `--fix-from` is present, operate in **fix mode**. Otherwise, check for `--draft` to determine placement mode. @@ -77,18 +77,17 @@ mkdir -p "$OUTPUT_DIR" ### 2a. UPDATE-IN-PLACE mode (default — no `--draft`) -Select the agent based on the `--no-jtbd` flag: - -- **If `--no-jtbd` is present**: dispatch `docs-tools:docs-writer` (feature-based writing) -- **Otherwise (default)**: dispatch `docs-tools:docs-writer-jtbd` (JTBD writing) +Always dispatch `docs-tools:docs-writer`. Pass the content paradigm in the prompt so the agent reads the correct paradigm reference file. **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` -- `description`: `Write documentation for ` +- `subagent_type`: `docs-tools:docs-writer` +- `description`: `Write documentation for ` **Prompt (AsciiDoc):** -> Write complete AsciiDoc documentation based on the documentation plan for ticket ``. +> Write complete AsciiDoc documentation based on the documentation plan for ``. +> +> **Content paradigm: ** > > Read the plan from: `` > @@ -107,7 +106,9 @@ Select the agent based on the `--no-jtbd` flag: **Prompt (MkDocs):** -> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket ``. +> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ``. +> +> **Content paradigm: ** > > Read the plan from: `` > @@ -126,15 +127,17 @@ Select the agent based on the `--no-jtbd` flag: ### 2b. DRAFT mode (`--draft`) -Select the agent based on the `--no-jtbd` flag (same logic as 2a). +Always dispatch `docs-tools:docs-writer` (same agent as 2a). Pass the content paradigm in the prompt. **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` -- `description`: `Write documentation for ` +- `subagent_type`: `docs-tools:docs-writer` +- `description`: `Write documentation for ` **Prompt (AsciiDoc, draft):** -> Write complete AsciiDoc documentation based on the documentation plan for ticket ``. +> Write complete AsciiDoc documentation based on the documentation plan for ``. +> +> **Content paradigm: ** > > Read the plan from: `` > @@ -161,7 +164,9 @@ Select the agent based on the `--no-jtbd` flag (same logic as 2a). **Prompt (MkDocs, draft):** -> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket ``. +> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ``. +> +> **Content paradigm: ** > > Read the plan from: `` > @@ -190,15 +195,17 @@ Select the agent based on the `--no-jtbd` flag (same logic as 2a). When invoked with `--fix-from`, the skill applies targeted corrections to existing drafts. -Select the agent based on the `--no-jtbd` flag (same logic as 2a). +Always dispatch `docs-tools:docs-writer` (same agent as 2a). Pass the content paradigm in the prompt. **Agent tool parameters:** -- `subagent_type`: `docs-tools:docs-writer` or `docs-tools:docs-writer-jtbd` -- `description`: `Fix documentation for ` +- `subagent_type`: `docs-tools:docs-writer` +- `description`: `Fix documentation for ` **Prompt:** -> Apply fixes to documentation drafts based on technical review feedback for ticket ``. +> Apply fixes to documentation drafts based on technical review feedback for ``. +> +> **Content paradigm: ** > > Read the review report from: `` > Drafts location: `/` From 2751d064f0458600b0b39faa2a26fa5b98e8bbb7 Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 14:08:00 +0000 Subject: [PATCH 06/10] Fix review issues: stale paradigm wording, missing --paradigm in fix loops - Replace hardcoded "Feature-based organization" with paradigm-neutral wording in docs-planner.md - Narrow scaffold format contract from to mkdocs-only - Add --paradigm to tech review fix iteration in orchestrator skill - Add Content paradigm to writer fix prompt in legacy command - Label bare code blocks in paradigm reference files Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/docs-planner.md | 2 +- plugins/docs-tools/commands/docs-workflow.md | 2 ++ plugins/docs-tools/reference/paradigm-jtbd.md | 2 +- plugins/docs-tools/reference/paradigm-user-stories.md | 2 +- plugins/docs-tools/skills/docs-orchestrator/SKILL.md | 4 ++-- 5 files changed, 7 insertions(+), 5 deletions(-) diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index 93fec008..43f94f86 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -93,7 +93,7 @@ Run doc impact assessment as the **first analytical step** when multiple issues 4. Create a documentation plan with: - Recommended module structure (concepts, procedures, references) - - Feature-based organization with parent topics per feature + - Paradigm-aligned organization with parent topics (see Content paradigm section above) - Priority ranking for documentation tasks - Dependencies between documentation pieces - **Reference links** to source materials for each recommendation diff --git a/plugins/docs-tools/commands/docs-workflow.md b/plugins/docs-tools/commands/docs-workflow.md index 2b166ec6..c9682a53 100644 --- a/plugins/docs-tools/commands/docs-workflow.md +++ b/plugins/docs-tools/commands/docs-workflow.md @@ -820,6 +820,8 @@ Launch the `docs-tools:docs-writer` agent with this prompt: > The technical reviewer found issues in the documentation for ticket ``. > +> **Content paradigm: ** +> > Read the technical review report at: `` > > Address all **Critical issues** and **Significant issues** listed in the report. Edit the files in place. diff --git a/plugins/docs-tools/reference/paradigm-jtbd.md b/plugins/docs-tools/reference/paradigm-jtbd.md index f1caaacf..950b0ed6 100644 --- a/plugins/docs-tools/reference/paradigm-jtbd.md +++ b/plugins/docs-tools/reference/paradigm-jtbd.md @@ -110,7 +110,7 @@ Parent Topics must include: - An overview of the high-level steps to achieve the goal, with links to related content Example Parent Topic outline: -``` +```text Title: Improve application performance Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. diff --git a/plugins/docs-tools/reference/paradigm-user-stories.md b/plugins/docs-tools/reference/paradigm-user-stories.md index cfba6a50..64127929 100644 --- a/plugins/docs-tools/reference/paradigm-user-stories.md +++ b/plugins/docs-tools/reference/paradigm-user-stories.md @@ -79,7 +79,7 @@ Parent Topics must include: - An overview of common tasks and their sequence, with links to related content Example Parent Topic outline: -``` +```text Title: Horizontal pod autoscaler Description: [What] Automatically adjusts the number of pod replicas based on CPU, memory, or custom metrics. [When] Use when workloads have variable resource demands. Overview: The HPA controller monitors metrics and adjusts replica counts within configured bounds. diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 207ba958..7bc9694a 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -215,7 +215,7 @@ Build the args string for the step skill: - `requirements`: `[--pr ]... [--jql ] [--tickets ] [--inputs ]...` - `planning`: `[--paradigm ]` - `prepare-branch`: `[--draft]` - - `scaffold`: `--format [--draft]` + - `scaffold`: `--format mkdocs [--draft]` - `writing`: `--format [--draft] [--paradigm ]` - `style-review`: `--format ` - `create-jira`: `--project ` @@ -244,7 +244,7 @@ The technical review step runs in a loop until confidence is acceptable or three 3. If `HIGH` → mark completed, proceed to next step 4. If `MEDIUM` or `LOW` and fewer than 3 iterations completed → run the fix skill: ``` - Skill: docs-tools:docs-workflow-writing, args: " --base-path --fix-from /technical-review/review.md" + Skill: docs-tools:docs-workflow-writing, args: " --base-path --fix-from /technical-review/review.md --paradigm " ``` Then re-run the reviewer (go to step 1) 5. After 3 iterations without reaching `HIGH`: From da0f04efdefc76af654fce1cf8c0d1f97700baee Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 16:40:30 +0000 Subject: [PATCH 07/10] Decouple review steps from placement mode, use manifest as source of truth Review and fix steps now read the writing manifest to find file locations instead of branching on --draft. This removes fragile flag-threading and eliminates conditional prompt duplication in downstream steps. - docs-reviewer: prompt-driven source paths, remove JIRA ID path coupling - tech-review/style-review: single prompt reads manifest, no --draft branch - writing fix mode: read manifest instead of assuming drafts location - prepare-branch: generalize $1 from "JIRA ticket ID" to "Workflow ID" - orchestrator: clarify folder structure for both placement modes Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/docs-reviewer.md | 40 +++++++++---------- .../skills/docs-orchestrator/SKILL.md | 12 ++++-- .../docs-workflow-prepare-branch/SKILL.md | 2 +- .../docs-workflow-style-review/SKILL.md | 36 ++++++++++------- .../skills/docs-workflow-tech-review/SKILL.md | 29 ++++++++------ .../skills/docs-workflow-writing/SKILL.md | 11 +++-- 6 files changed, 71 insertions(+), 59 deletions(-) diff --git a/plugins/docs-tools/agents/docs-reviewer.md b/plugins/docs-tools/agents/docs-reviewer.md index e67d130e..3853dee3 100644 --- a/plugins/docs-tools/agents/docs-reviewer.md +++ b/plugins/docs-tools/agents/docs-reviewer.md @@ -39,14 +39,15 @@ Apply all review skills listed below. Process one file at a time, write findings ## When invoked -1. **Extract the JIRA ID** from the task context or source folder: - - Look for patterns like `JIRA-123`, `RHAISTRAT-248`, `OSDOCS-456` - - Convert to lowercase for folder naming: `jira-123`, `rhaistrat-248` - - This ID determines the drafts folder location +1. **Determine the source location** from the task prompt: + - If the prompt specifies a source path (e.g., `/writing/` or a repo location), use that + - If no path is specified, fall back to `.claude/docs/drafts//` (legacy convention) + - Within the source location, look for modules in a `modules/` subfolder and assemblies/pages at the root -2. **Locate source drafts** from `.claude/docs/drafts//`: - - Modules in: `.claude/docs/drafts//modules/` - - Assemblies in: `.claude/docs/drafts//` +2. **Extract the workflow ID** for the report header: + - From the task prompt (e.g., "Review docs for PROJ-123" → `PROJ-123`) + - From the source folder name as a fallback + - This is used only for labeling the report, not for path construction 3. **Determine the error level** to report (default: suggestion): - **suggestion**: Show all issues (suggestions + warnings + errors) @@ -61,8 +62,8 @@ Apply all review skills listed below. Process one file at a time, write findings - Run Vale once. Fix obvious errors and warnings where the fix is clear. Skip ambiguous issues. Do NOT re-run Vale repeatedly. - Read and apply all applicable review skills from the table above (use `docs-tools:docs-review-modular-docs` for .adoc files). Record findings. -6. **Edit files in place** in `.claude/docs/drafts//`: - - Apply all fixes directly to the source files in the drafts folder +6. **Edit files in place** at the source location: + - Apply all fixes directly to the source files - Do NOT create copies in a separate reviews folder 7. **Write findings for this file to the report** before moving to the next file. @@ -189,11 +190,13 @@ Severity levels align with Vale rule levels and Red Hat documentation requiremen ## Output location -**All files are edited in place in `.claude/docs/drafts//`. The review report is saved to the same drafts folder.** +**All files are edited in place at the source location. The review report is saved to the output path specified in the task prompt.** -``` -.claude/docs/drafts// -├── _review_report.md # Combined review report for all files +When invoked by the orchestrator, the report path is provided explicitly (e.g., `/style-review/review.md`). When invoked standalone or by the legacy command, save to `_review_report.md` in the source folder. + +```text +/ +├── _review_report.md # Combined review report (standalone/legacy) ├── assembly_.adoc # Reviewed assembly files (edited in place) └── modules/ # Reviewed module files (edited in place) ├── .adoc @@ -201,23 +204,16 @@ Severity levels align with Vale rule levels and Red Hat documentation requiremen └── .adoc ``` -### JIRA ID extraction - -Extract the JIRA ID from: -1. The drafts folder path: `.claude/docs/drafts/rhaistrat-248/` -> `rhaistrat-248` -2. The task context or user request: "Review docs for RHAISTRAT-248" -> `rhaistrat-248` -3. Use lowercase with hyphens - ### Review report -Save the combined review report to: `.claude/docs/drafts//_review_report.md` +Save the combined review report to the path specified in the task prompt. If no output path is given, save to `/_review_report.md`. Use this report format: ```markdown # Documentation Review Report -**Source**: Ticket: +**Source**: **Date**: YYYY-MM-DD ## Summary diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 7bc9694a..da96ffea 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -104,7 +104,7 @@ The workflow ID is sanitized for use as a directory name: convert to lowercase, ### Folder structure -``` +```text .claude/docs// requirements/ requirements.md @@ -115,9 +115,10 @@ The workflow ID is sanitized for use as a directory name: convert to lowercase, prepare-branch/ branch-info.md writing/ - _index.md - assembly_*.adoc (or docs/*.md for mkdocs) - modules/ + _index.md (manifest — always present, lists all file locations) + modules/ (draft mode only — actual files live here) + assembly_*.adoc (draft mode only) + docs/*.md (draft mode only, mkdocs) technical-review/ review.md style-review/ @@ -126,6 +127,8 @@ The workflow ID is sanitized for use as a directory name: convert to lowercase, _.json ``` +In UPDATE-IN-PLACE mode, `writing/` contains only the manifest (`_index.md`). The actual documentation files are at their repo locations as listed in the manifest. In DRAFT mode, `writing/` contains both the manifest and the files themselves. + Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its `inputs` list. The orchestrator passes the base path `.claude/docs//` — step skills derive everything else by convention. ## Progress file @@ -217,6 +220,7 @@ Build the args string for the step skill: - `prepare-branch`: `[--draft]` - `scaffold`: `--format mkdocs [--draft]` - `writing`: `--format [--draft] [--paradigm ]` + - `technical-review`: *(no additional flags — reads manifest)* - `style-review`: `--format ` - `create-jira`: `--project ` diff --git a/plugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.md b/plugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.md index c3009f4e..679282f5 100644 --- a/plugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.md @@ -14,7 +14,7 @@ Step skill for the docs-orchestrator pipeline. Creates a clean working branch fr ## Arguments -- `$1` — JIRA ticket ID (required) +- `$1` — Workflow ID (required). Used as the branch name (lowercased). - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--draft` — If present, skip branch creation entirely diff --git a/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md b/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md index 2b3d5b31..6245eaa6 100644 --- a/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-style-review -description: Style guide compliance review of documentation drafts. Dispatches the docs-reviewer agent with Vale linting and 18+ style guide review skills. -argument-hint: --base-path --format +description: Style guide compliance review of documentation. Dispatches the docs-reviewer agent with Vale linting and 18+ style guide review skills. Reads the writing manifest to locate files regardless of placement mode. +argument-hint: --base-path --format allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -11,19 +11,19 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments -- `$1` — JIRA ticket ID (required) +- `$1` — Workflow ID (JIRA ticket, doc set name, or any identifier) (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--format ` — Documentation format (default: `adoc`) ## Input -``` -/writing/ +```text +/writing/_index.md (manifest — lists all files and their locations) ``` ## Output -``` +```text /style-review/review.md ``` @@ -31,12 +31,12 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ### 1. Parse arguments -Extract the ticket ID, `--base-path`, and `--format` from the args string. +Extract the workflow ID, `--base-path`, and `--format` from the args string. Set the paths: ```bash -DRAFTS_DIR="${BASE_PATH}/writing" +MANIFEST="${BASE_PATH}/writing/_index.md" OUTPUT_DIR="${BASE_PATH}/style-review" OUTPUT_FILE="${OUTPUT_DIR}/review.md" mkdir -p "$OUTPUT_DIR" @@ -48,14 +48,17 @@ Dispatch the `docs-tools:docs-reviewer` agent with a format-specific prompt. **Agent tool parameters:** - `subagent_type`: `docs-tools:docs-reviewer` -- `description`: `Review documentation for ` +- `description`: `Review documentation for ` **Prompt (AsciiDoc — `--format adoc`):** -> Review the AsciiDoc documentation drafts for ticket ``. -> Source drafts location: `/` +> Review the AsciiDoc documentation for ``. +> +> The documentation manifest is at: `` > -> **Edit files in place**. Do NOT create copies. +> Read the manifest to find all file locations, then review every listed .adoc file. +> +> **Edit files in place** at their listed locations. Do NOT create copies. > > For each file: > 1. Run Vale linting once (use the `vale-tools:lint-with-vale` skill) @@ -70,10 +73,13 @@ Dispatch the `docs-tools:docs-reviewer` agent with a format-specific prompt. **Prompt (MkDocs — `--format mkdocs`):** -> Review the Material for MkDocs Markdown documentation drafts for ticket ``. -> Source drafts location: `/` +> Review the Material for MkDocs Markdown documentation for ``. +> +> The documentation manifest is at: `` +> +> Read the manifest to find all file locations, then review every listed .md file. > -> **Edit files in place**. Do NOT create copies. +> **Edit files in place** at their listed locations. Do NOT create copies. > > For each file: > 1. Run Vale linting once (use the `vale-tools:lint-with-vale` skill) diff --git a/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md b/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md index 45f66d4c..73095304 100644 --- a/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-tech-review/SKILL.md @@ -1,7 +1,7 @@ --- name: docs-workflow-tech-review -description: Technical accuracy review of documentation drafts. Dispatches the technical-reviewer agent. Output includes confidence rating (HIGH/MEDIUM/LOW) Iteration logic is owned by the orchestrator, not this skill. -argument-hint: --base-path +description: Technical accuracy review of documentation. Dispatches the technical-reviewer agent. Reads the writing manifest to locate files regardless of placement mode. Output includes confidence rating (HIGH/MEDIUM/LOW). Iteration logic is owned by the orchestrator, not this skill. +argument-hint: --base-path allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent, WebSearch, WebFetch --- @@ -13,18 +13,18 @@ This skill performs a single review pass. The iteration loop (re-running with fi ## Arguments -- `$1` — JIRA ticket ID (required) +- `$1` — Workflow ID (JIRA ticket, doc set name, or any identifier) (required) - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) ## Input -``` -/writing/ +```text +/writing/_index.md (manifest — lists all files and their locations) ``` ## Output -``` +```text /technical-review/review.md ``` @@ -32,12 +32,12 @@ This skill performs a single review pass. The iteration loop (re-running with fi ### 1. Parse arguments -Extract the ticket ID and `--base-path` from the args string. +Extract the workflow ID and `--base-path` from the args string. Set the paths: ```bash -DRAFTS_DIR="${BASE_PATH}/writing" +MANIFEST="${BASE_PATH}/writing/_index.md" OUTPUT_DIR="${BASE_PATH}/technical-review" OUTPUT_FILE="${OUTPUT_DIR}/review.md" mkdir -p "$OUTPUT_DIR" @@ -45,17 +45,20 @@ mkdir -p "$OUTPUT_DIR" ### 2. Dispatch agent -Dispatch the `docs-tools:technical-reviewer` agent with the following prompt. +Dispatch the `docs-tools:technical-reviewer` agent. **Agent tool parameters:** - `subagent_type`: `docs-tools:technical-reviewer` -- `description`: `Technical review of documentation for ` +- `description`: `Technical review of documentation for ` **Prompt:** -> Perform a technical review of the documentation drafts for ticket ``. -> Source drafts location: `/` -> Review all .adoc and .md files. Follow your standard review methodology. +> Perform a technical review of the documentation for ``. +> +> The documentation manifest is at: `` +> +> Read the manifest to find all file locations, then review every listed file. Follow your standard review methodology. +> > Save your review report to: `` > > The report must include an `Overall technical confidence: HIGH|MEDIUM|LOW` line. diff --git a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md index 5b8b3137..7be640ca 100644 --- a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md @@ -72,6 +72,7 @@ Set the paths: INPUT_FILE="${BASE_PATH}/planning/plan.md" OUTPUT_DIR="${BASE_PATH}/writing" OUTPUT_FILE="${OUTPUT_DIR}/_index.md" +MANIFEST="${OUTPUT_FILE}" mkdir -p "$OUTPUT_DIR" ``` @@ -193,7 +194,7 @@ Always dispatch `docs-tools:docs-writer` (same agent as 2a). Pass the content pa ### 2c. Fix mode — dispatch writer agent for corrections -When invoked with `--fix-from`, the skill applies targeted corrections to existing drafts. +When invoked with `--fix-from`, the skill applies targeted corrections to existing documentation. Always dispatch `docs-tools:docs-writer` (same agent as 2a). Pass the content paradigm in the prompt. @@ -203,19 +204,21 @@ Always dispatch `docs-tools:docs-writer` (same agent as 2a). Pass the content pa **Prompt:** -> Apply fixes to documentation drafts based on technical review feedback for ``. +> Apply fixes to documentation based on technical review feedback for ``. > > **Content paradigm: ** > > Read the review report from: `` -> Drafts location: `/` +> +> The documentation manifest is at: `` +> Read the manifest to find all file locations. > > For each issue flagged in the review: > 1. If the fix is clear and unambiguous, apply it directly > 2. If the issue requires broader context or judgment, skip it > 3. Do NOT rewrite content that was not flagged > -> Edit files in place. Do NOT create copies or new files. +> Edit files in place at their listed locations. Do NOT create copies or new files. In fix mode, the skill does not create new modules or restructure content. From f6ae22a5ff37e1c395205bba5f8b47912b66177e Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 17:33:52 +0000 Subject: [PATCH 08/10] Fix review issues: unified source handling, manifest schema, YAML defaults MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove modal split between single-ticket and multi-source mode in requirements handling — $1 now auto-detects JIRA ticket pattern and all source flags are always additive (4.4). Add manifest schema for _index.md inter-step contract (4.1). Add YAML workflow defaults with CLI > YAML > global precedence (6.4). Fix gerund procedure titles in user-stories paradigm reference (5.1). Replace non-standard plan template placeholders with [REPLACE: ...] directive (5.2). Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/docs-planner.md | 15 +++----- .../docs-tools/agents/requirements-analyst.md | 14 +------- .../reference/paradigm-user-stories.md | 10 +++--- .../skills/docs-orchestrator/SKILL.md | 24 +++++++++---- .../defaults/docs-docset-workflow.yaml | 3 ++ .../docs-workflow-requirements/SKILL.md | 36 ++++++------------- .../skills/docs-workflow-writing/SKILL.md | 29 +++++++++++++++ 7 files changed, 71 insertions(+), 60 deletions(-) diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index 43f94f86..9a687f3e 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -346,17 +346,10 @@ Use the paradigm-specific header variant from the paradigm reference if applicab [* Developer: Primary user creating containerized applications] [* SysAdmin: Manages the platform where containers are deployed] -## [Paradigm-specific section 1] - -[REPLACE: Use the section header and content format from the paradigm reference file. -For JTBD: "What is the main JTBD? What user goal is being accomplished? What pain point is being avoided?" -For user-stories: "What are the primary user stories?"] - -## [Paradigm-specific section 2] - -[REPLACE: Use the section header and content format from the paradigm reference file. -For JTBD: "How does the JTBD(s) relate to the overall real-world workflow for the user?" -For user-stories: "How do these features relate to the user's workflow?"] +[REPLACE: Insert the two paradigm-specific sections from the paradigm reference file. +The "Plan template: paradigm-specific sections" in the paradigm reference defines the exact +## section headers and content format. Copy the Section 1 and Section 2 headings verbatim +from the reference and populate them with your research findings.] ## What high level steps does the user need to take to accomplish the goal? diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index 966b16fa..bc5148f2 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -32,7 +32,7 @@ Proceeding with incorrect or assumed information leads to: ## Parse arguments -- `$1` — Workflow ID. Treated as a JIRA ticket ID by default (fetched via jira-reader). **Exception**: if any of `--jql`, `--tickets`, or `--inputs` flags are provided, `$1` is treated as a plain workflow identifier (not fetched as a JIRA ticket). Use only the flags for actual source input. +- `$1` — Workflow ID. If it matches `[A-Z]+-[0-9]+` (case-insensitive), it is also auto-included as a JIRA ticket source. - `--base-path ` — Base output directory for all step outputs - `--pr ` — PR/MR URLs (repeatable) - `--jql ` — JQL query for bulk JIRA ticket fetch (uses `jira_reader.py --jql --fetch-details`) @@ -61,18 +61,6 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor **Local files:** Read directly using the Read tool. -### Multi-source mode - -When `--jql`, `--tickets`, or `--inputs` are provided, gather ALL sources before analysis: - -1. Fetch all JIRA tickets from `--jql` (with `--fetch-details`) and `--tickets` -2. Run `--graph` on each fetched ticket to discover linked Google Docs and PRs -3. Process each `--inputs` value based on auto-detected type -4. Process each `--pr` URL -5. Merge all gathered content, then proceed with the standard analysis methodology below - -All sources are combined into a single unified `requirements.md` in the same format as single-ticket mode. - ## When invoked 1. Gather source materials: diff --git a/plugins/docs-tools/reference/paradigm-user-stories.md b/plugins/docs-tools/reference/paradigm-user-stories.md index 64127929..7e965153 100644 --- a/plugins/docs-tools/reference/paradigm-user-stories.md +++ b/plugins/docs-tools/reference/paradigm-user-stories.md @@ -34,7 +34,7 @@ Structure documentation around product capabilities, features, and components Choose the categorization scheme that best fits the product and its users. Do not use a fixed category list — adapt to the product domain. 5. **Use descriptive, feature-focused titles**: - - **Good**: "Configuring horizontal pod autoscaling" (clear feature reference) + - **Good**: "Configure horizontal pod autoscaling" (clear feature reference) - **Bad**: "Scale applications based on demand" (too abstract) 6. **Apply active phrasing for procedures**: Use imperatives and name the feature (e.g., "Configure RBAC policies", "Install the monitoring agent"). @@ -61,12 +61,12 @@ For each documentation need, identify the user story and map it to the feature h **Step 2: Map to the feature hierarchy** - **Area**: Broad domain derived from the product (e.g., "Networking", "Security", "Storage") - **Feature / Parent Topic**: The specific capability (e.g., "Horizontal Pod Autoscaler") -- **Tasks / Child Modules**: Specific procedures, concepts, and references for the feature (e.g., "Configuring HPA thresholds", "HPA architecture", "HPA parameters") +- **Tasks / Child Modules**: Specific procedures, concepts, and references for the feature (e.g., "Configure HPA thresholds", "HPA architecture", "HPA parameters") TOC nesting rules: - Headings in TOCs must not exceed **3 levels** of nesting. - **Areas do not count** toward nesting depth because they contain no content — they are organizational groupings only. -- Example: `Networking (area) → Ingress Controller (Feature, level 1) → Configuring route timeouts (task, level 2) → Route timeout parameters (reference, level 3)` +- Example: `Networking (area) → Ingress Controller (Feature, level 1) → Configure route timeouts (task, level 2) → Route timeout parameters (reference, level 3)` **Step 3: Plan Parent Topics** @@ -132,7 +132,7 @@ Use clear, descriptive titles that name the feature or component: | Type | Bad (Too abstract) | Good (Feature-descriptive) | |------|-------------------|---------------------------| | CONCEPT | "How autoscaling responds to demand" | "Horizontal pod autoscaler architecture" | -| PROCEDURE | "Scale applications automatically" | "Configuring horizontal pod autoscaling" | +| PROCEDURE | "Scale applications automatically" | "Configure horizontal pod autoscaling" | | REFERENCE | "Autoscaling configuration options" | "HPA configuration parameters" | | ASSEMBLY | "Scale applications based on demand" | "Horizontal pod autoscaler" | @@ -148,7 +148,7 @@ Use clear, descriptive titles that name the feature or component: - **Length**: 3-11 words, sentence case, no end punctuation - **Feature-descriptive**: Name the feature or component clearly - **Concept titles**: Noun phrase naming the feature (e.g., "Horizontal pod autoscaler architecture") -- **Procedure titles**: Imperative verb phrase naming the feature (e.g., "Configuring horizontal pod autoscaling") +- **Procedure titles**: Imperative verb phrase naming the feature (e.g., "Configure horizontal pod autoscaling") - **Reference titles**: Noun phrase for the data set (e.g., "HPA configuration parameters") - **Assembly titles** (AsciiDoc only): Feature name (e.g., "Horizontal pod autoscaler") - Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index da96ffea..5d720ffa 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -22,10 +22,7 @@ if [[ -z "${JIRA_AUTH_TOKEN:-}" ]]; then fi ``` -1. **JIRA token check** — require `JIRA_AUTH_TOKEN` only when JIRA access is needed: - - If `--jql` or `--tickets` flags are passed → **STOP** if unset (JIRA is explicitly requested) - - If the workflow is the default `docs-workflow` → **STOP** if unset (default workflow requires JIRA) - - Otherwise (custom workflow without JIRA flags) → skip the check +1. **JIRA token check** — require `JIRA_AUTH_TOKEN` if `$1` matches a JIRA ticket pattern (`[A-Z]+-[0-9]+`), or `--jql`/`--tickets` flags are passed. Otherwise skip the check. 2. Warn (don't stop) if `GITHUB_TOKEN` or `GITLAB_TOKEN` are unset 3. Install hooks (safe to re-run): @@ -35,7 +32,7 @@ bash scripts/setup-hooks.sh ## Parse arguments -- `$1` — Workflow ID (required). For the default `docs-workflow`, this is a JIRA ticket ID. For custom workflows (e.g., `--workflow docset`), this can be any identifier such as a doc set name. If missing, STOP and ask the user. +- `$1` — Workflow ID (required). If it matches a JIRA ticket pattern (`[A-Z]+-[0-9]+`), it is also auto-included as a JIRA ticket source. If missing, STOP and ask the user. - `--workflow ` — Use `.claude/docs-.yaml` instead of `docs-workflow.yaml` - `--pr ` — PR/MR URLs (repeatable, accumulated into a list) - `--inputs ` — Additional input sources (repeatable, accumulated into a list). Each value can be a local file path, Google Drive URL, or web URL. Forwarded to the requirements step for auto-detection and processing. @@ -57,7 +54,22 @@ bash scripts/setup-hooks.sh ### 2. Read the YAML -Read the YAML file and extract the ordered step list. Each step has: `name`, `skill`, `description`, optional `when`, and optional `inputs`. +Read the YAML file and extract the ordered step list and optional defaults. Each step has: `name`, `skill`, `description`, optional `when`, and optional `inputs`. + +The YAML may include an optional `defaults` block at the workflow level: + +```yaml +workflow: + name: docs-docset-workflow + description: ... + defaults: + format: mkdocs + paradigm: user-stories + steps: + - ... +``` + +CLI flags override YAML defaults. YAML defaults override global defaults (`format: adoc`, `paradigm: jtbd`). Precedence: **CLI flag > YAML default > global default**. ### 3. Evaluate `when` conditions diff --git a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml index 589de21e..69a04e73 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml +++ b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml @@ -5,6 +5,9 @@ workflow: Gathers requirements from JIRA tickets, local files, and Google Drive. Plans, scaffolds, writes, and reviews the full doc set. + defaults: + format: mkdocs + # All step outputs go to: .claude/docs/// # Each step reads its inputs from upstream step folders by convention. steps: diff --git a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md index 89d77387..002efb5e 100644 --- a/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md @@ -11,7 +11,7 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract: ## Arguments -- `$1` — Workflow ID (required). A JIRA ticket ID for single-ticket workflows, or a doc set name for multi-source workflows. +- `$1` — Workflow ID (required). If it matches a JIRA ticket pattern (`[A-Z]+-[0-9]+`), it is also fetched as a JIRA ticket source automatically. - `--base-path ` — Base output path (e.g., `.claude/docs/proj-123`) - `--pr ` — PR/MR URL to include in analysis (repeatable) - `--jql ` — JQL query for bulk JIRA ticket fetch (optional) @@ -38,10 +38,6 @@ OUTPUT_FILE="${OUTPUT_DIR}/requirements.md" mkdir -p "$OUTPUT_DIR" ``` -Determine the mode: -- **Multi-source mode**: If any of `--jql`, `--tickets`, or `--inputs` are present. `$1` is a workflow ID only. -- **Single-ticket mode**: If none of those flags are present. `$1` is a JIRA ticket ID. - ### 2. Dispatch agent Dispatch the `docs-tools:requirements-analyst` agent with the following prompt. @@ -50,39 +46,29 @@ Dispatch the `docs-tools:requirements-analyst` agent with the following prompt. - `subagent_type`: `docs-tools:requirements-analyst` - `description`: `Analyze requirements for ` -**Prompt (single-ticket mode):** +**Prompt:** -> Analyze documentation requirements for JIRA ticket ``. -> -> Manually-provided PR/MR URLs to include in analysis (merge with any auto-discovered URLs, dedup): -> - `` -> - `` +> Analyze documentation requirements for workflow ``. > -> Save your complete analysis to: `` -> -> Follow your standard analysis methodology (JIRA fetch, ticket graph traversal, PR/MR analysis, web search expansion). Format the output as structured markdown for the next stage. - -**Prompt (multi-source mode):** - -> Analyze documentation requirements from multiple sources for workflow ``. +> **JIRA tickets** (fetch all, run --graph on each to discover linked docs and PRs): +> - `` +> - `` > -> **JIRA sources** (fetch all, run --graph on each): -> - JQL query: `` (use --fetch-details) -> - Explicit tickets: `` +> **JQL query** (use --fetch-details): +> - `` > > **Additional input sources** (auto-detect type for each): > - `` -> - `` > > **PR/MR URLs** (merge with any auto-discovered URLs, dedup): > - `` -> - `` > > Save your complete analysis to: `` > -> Gather ALL sources before analysis. Process each --inputs value by auto-detecting its type (Google Drive URL → gdoc2md.py, web URL → article_extractor.py, local path → Read tool). Then follow your standard analysis methodology. Produce a single unified requirements.md covering all sources. +> Gather all sources before analysis. Follow your standard analysis methodology. +> Format the output as structured markdown for the next stage. -Each section in the prompt is conditional — include only if the corresponding flags were provided. If no `--jql` was passed, omit the JQL line. If no `--inputs` were passed, omit the inputs section. Etc. +Each section is conditional — include only if sources of that type exist. If `$1` matched the JIRA pattern, it appears in the JIRA tickets list. ### 3. Verify output diff --git a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md index 7be640ca..c5e631ff 100644 --- a/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md +++ b/plugins/docs-tools/skills/docs-workflow-writing/SKILL.md @@ -58,6 +58,35 @@ Files are written directly to their correct repo locations. A manifest is create docs/*.md (MkDocs mode) ``` +### Manifest format (`_index.md`) + +The manifest is a Markdown file listing all documentation files created or updated by the writing step. Review steps and fix mode read this file to locate content regardless of placement mode. + +```markdown +# Writing Manifest + +**Workflow ID**: +**Placement mode**: UPDATE-IN-PLACE | DRAFT +**Format**: adoc | mkdocs +**Date**: YYYY-MM-DD + +## Files + +| Path | Type | Module type | Status | +|------|------|-------------|--------| +| `path/to/file.adoc` | assembly | ASSEMBLY | created | +| `path/to/modules/con_name.adoc` | module | CONCEPT | created | +| `path/to/modules/proc_name.adoc` | module | PROCEDURE | created | +| `path/to/modules/ref_name.adoc` | module | REFERENCE | created | +``` + +- **Path**: Absolute or repo-relative path to the file. In UPDATE-IN-PLACE mode, these are repo locations. In DRAFT mode, these are paths within `/writing/`. +- **Type**: `assembly` or `module` (or `page` for MkDocs) +- **Module type**: `ASSEMBLY`, `CONCEPT`, `PROCEDURE`, `REFERENCE` (or `page` for MkDocs) +- **Status**: `created` (new file) or `updated` (existing file modified) + +Review steps iterate the `## Files` table to locate every file for review. + ## Execution ### 1. Parse arguments From 42f85aa8786e8fec9918968ef17cff550bd29d1d Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 17:37:14 +0000 Subject: [PATCH 09/10] Fix hardcoded user-stories reference in planner template rules The template population rule said "User stories" which hardcodes one paradigm. Replace with paradigm-neutral language that defers to the paradigm reference file, consistent with the runtime paradigm selection. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/docs-planner.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index 9a687f3e..c79c0316 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -322,7 +322,7 @@ Copy these sections verbatim from the completed full plan. Do not add sections t - **Replace ALL `[REPLACE: ...]` text** with real content derived from your research — never output the bracket instructions themselves - **Personas**: Select 1-3 personas from the persona reference list below. Output ONLY the selected personas with a brief relevance note. Do NOT include the full persona reference list in the output - **New Docs / Updated Docs**: Replace the example entries with actual module names, types, and content outlines from your planning. The entries shown (e.g., "Actual Module Title (Concept)") are structural examples, not headings to keep -- **User stories**: Replace with actual user stories derived from your analysis +- **Paradigm-specific sections**: Replace with real content from your analysis, using the section headers and format defined in the paradigm reference file ```markdown # Documentation Plan From 21ccfa080b0cc1cb81880502d631c56e1b63cee6 Mon Sep 17 00:00:00 2001 From: Alex McLeod Date: Fri, 27 Mar 2026 17:54:06 +0000 Subject: [PATCH 10/10] Remove redundant --format markdown flag and inline YAML example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The article_extractor.py defaults to markdown, so --format markdown is noise. The orchestrator YAML defaults example duplicates the real file at defaults/docs-docset-workflow.yaml — replace with a pointer. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/agents/requirements-analyst.md | 4 ++-- .../docs-tools/skills/docs-orchestrator/SKILL.md | 15 +-------------- 2 files changed, 3 insertions(+), 16 deletions(-) diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index bc5148f2..ea3fefcb 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -56,7 +56,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-convert-gdoc-md/scripts/gdoc2md.py "" --format markdown +python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "" ``` **Local files:** Read directly using the Read tool. @@ -462,7 +462,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/redhat-docs-toc/scripts/toc_extractor.py -- Download and extract content from web pages: ```bash -python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." --format markdown +python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..." ``` ### Converting Google Drive documents with docs-convert-gdoc-md diff --git a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md index 5d720ffa..225944d7 100644 --- a/plugins/docs-tools/skills/docs-orchestrator/SKILL.md +++ b/plugins/docs-tools/skills/docs-orchestrator/SKILL.md @@ -56,20 +56,7 @@ bash scripts/setup-hooks.sh Read the YAML file and extract the ordered step list and optional defaults. Each step has: `name`, `skill`, `description`, optional `when`, and optional `inputs`. -The YAML may include an optional `defaults` block at the workflow level: - -```yaml -workflow: - name: docs-docset-workflow - description: ... - defaults: - format: mkdocs - paradigm: user-stories - steps: - - ... -``` - -CLI flags override YAML defaults. YAML defaults override global defaults (`format: adoc`, `paradigm: jtbd`). Precedence: **CLI flag > YAML default > global default**. +The YAML may include an optional `defaults` block at the workflow level (see `defaults/docs-docset-workflow.yaml` for an example). Supported keys: `format`, `paradigm`. CLI flags override YAML defaults. YAML defaults override global defaults (`format: adoc`, `paradigm: jtbd`). Precedence: **CLI flag > YAML default > global default**. ### 3. Evaluate `when` conditions