diff --git a/plugins/docs-tools/.claude-plugin/plugin.json b/plugins/docs-tools/.claude-plugin/plugin.json index 8201d0b7..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.15", + "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.md b/plugins/docs-tools/agents/docs-planner.md index d5ffcab6..c79c0316 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. 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,78 +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.** -## Jobs to Be Done (JTBD) framework +## Content paradigm -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. +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 JTBD matters for documentation planning +| 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 | -Applying JTBD to documentation planning produces measurable improvements: +If the task prompt does not specify a paradigm, default to `jtbd`. -- **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 +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 @@ -148,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) - - Assembly organization for user stories + - 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 @@ -255,14 +200,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 +215,26 @@ 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 - -### 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 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 + +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 + +**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) + +**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 @@ -396,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 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. +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 @@ -412,7 +322,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 +- **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 @@ -421,13 +331,14 @@ 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] +[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 JTBD analysis] +[REPLACE: Summarize why the user needs this content, derived from your analysis] ## Who is the target persona(s)? @@ -435,14 +346,10 @@ 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? - -[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] +[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? @@ -510,9 +417,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 — 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. @@ -593,15 +500,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. **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. **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. **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 +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-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/agents/docs-writer.md b/plugins/docs-tools/agents/docs-writer.md index b37f101d..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. -## Jobs to Be Done (JTBD) framework +## Content paradigm -Apply JTBD principles from the docs-planner agent. 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 outcome-driven titles with natural language: +If the task prompt does not specify a paradigm, default to `jtbd`. -| 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 +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 -- **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") +- **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/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index e5702ffe..ea3fefcb 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -30,6 +30,37 @@ 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. 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`) +- `--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 "" +``` + +**Local files:** Read directly using the Read tool. + ## When invoked 1. Gather source materials: @@ -428,12 +459,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/..." ``` +### Converting Google Drive documents with docs-convert-gdoc-md + +Convert Google Docs, Slides, and Sheets to Markdown/CSV: + +```bash +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/commands/docs-workflow.md b/plugins/docs-tools/commands/docs-workflow.md index 889d63cc..c9682a53 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 @@ -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 | 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`) | -| 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` | 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 | ## Output Structure @@ -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} }, @@ -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: @@ -611,6 +620,7 @@ 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` @@ -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`. @@ -802,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. @@ -1029,18 +1049,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 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 +1379,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 +1404,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..950b0ed6 --- /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: +```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. +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..7e965153 --- /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**: "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"). + +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., "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) → Configure 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: +```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. +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" | "Configure 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., "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-docset-scaffold/SKILL.md b/plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md new file mode 100644 index 00000000..eae6e0bc --- /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 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 + +- **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..225944d7 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] [--jtbd] [--user-stories] [--create-jira ] allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, AskUserQuestion, WebSearch, WebFetch --- @@ -22,7 +22,7 @@ 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` 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): @@ -32,11 +32,16 @@ bash scripts/setup-hooks.sh ## Parse arguments -- `$1` — JIRA ticket ID (required). 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. +- `--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 +- `--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 @@ -49,7 +54,9 @@ 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 (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 @@ -86,61 +93,70 @@ 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 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 -``` -.claude/docs/proj-123/ +```text +.claude/docs// requirements/ requirements.md planning/ plan.md + scaffold/ (docset workflow only) + scaffold-info.md 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/ 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. +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 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, + "paradigm": "jtbd", "create_jira_project": null, - "pr_urls": [] + "pr_urls": [], + "input_urls": [], + "jql": null, + "tickets": [] }, "step_order": ["requirements", "planning", "writing", ...], "steps": { @@ -170,7 +186,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 +194,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 +212,14 @@ 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`: `[--paradigm ]` - `prepare-branch`: `[--draft]` - - `writing`: `--format [--draft]` + - `scaffold`: `--format mkdocs [--draft]` + - `writing`: `--format [--draft] [--paradigm ]` + - `technical-review`: *(no additional flags — reads manifest)* - `style-review`: `--format ` - `create-jira`: `--project ` @@ -228,7 +247,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`: @@ -243,7 +262,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 +272,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..69a04e73 --- /dev/null +++ b/plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml @@ -0,0 +1,46 @@ +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. + + defaults: + format: mkdocs + + # 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-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 e756f3c7..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 @@ -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", ] @@ -55,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) diff --git a/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md b/plugins/docs-tools/skills/docs-workflow-planning/SKILL.md index 6fa451cb..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 agent. Invoked by the orchestrator. -argument-hint: --base-path +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,8 +11,9 @@ 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`) +- `--paradigm ` — Content paradigm (default: `jtbd`) ## 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 workflow ID, `--base-path`, and `--paradigm` from the args string. Default paradigm to `jtbd` if not specified. Set the paths: @@ -43,16 +44,18 @@ mkdir -p "$OUTPUT_DIR" ### 2. Dispatch agent -Dispatch the `docs-tools:docs-planner` agent with the following prompt. +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` -- `description`: `Create documentation plan for ` +- `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-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-requirements/SKILL.md b/plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md index 4a0d0a41..002efb5e 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). 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) +- `--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: @@ -41,21 +44,31 @@ 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:** -> Analyze documentation requirements for JIRA ticket ``. +> Analyze documentation requirements for workflow ``. > -> Manually-provided PR/MR URLs to include in analysis (merge with any auto-discovered URLs, dedup): +> **JIRA tickets** (fetch all, run --graph on each to discover linked docs and PRs): +> - `` +> - `` +> +> **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: `` > -> 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. +> Gather all sources before analysis. Follow your standard analysis methodology. +> 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. +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-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 59749cb3..c5e631ff 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 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,16 +18,18 @@ Supports three modes: ### Normal mode -- `$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 ` — Output format (default: `adoc`) - `--draft` — Use DRAFT placement mode (staging area) instead of UPDATE-IN-PLACE +- `--paradigm ` — Content paradigm (default: `jtbd`) ### Fix mode -- `$1` — JIRA ticket 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) +- `--paradigm ` — Content paradigm (default: `jtbd`) ## Input @@ -56,11 +58,40 @@ 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 -Extract the ticket ID, `--base-path`, `--format`, and `--draft` 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. @@ -70,18 +101,23 @@ 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" ``` ### 2a. UPDATE-IN-PLACE mode (default — no `--draft`) +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` -- `description`: `Write documentation for ` +- `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: `` > @@ -100,7 +136,9 @@ mkdir -p "$OUTPUT_DIR" **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: `` > @@ -119,13 +157,17 @@ mkdir -p "$OUTPUT_DIR" ### 2b. DRAFT mode (`--draft`) +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` -- `description`: `Write documentation for ` +- `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: `` > @@ -152,7 +194,9 @@ mkdir -p "$OUTPUT_DIR" **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: `` > @@ -179,25 +223,31 @@ mkdir -p "$OUTPUT_DIR" ### 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. **Agent tool parameters:** - `subagent_type`: `docs-tools:docs-writer` -- `description`: `Fix documentation for ` +- `description`: `Fix documentation for ` **Prompt:** -> Apply fixes to documentation drafts based on technical review feedback for ticket ``. +> 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.