From jtbd-tools
Generates JTBD-oriented Table of Contents from JSONL records or directories. Organizes by user jobs, workflow stages; outputs structured Markdown TOC following guidelines.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin jtbd-toolsThis skill is limited to using the following tools:
Generate a standalone, high-quality Jobs-To-Be-Done Table of Contents from JTBD analysis records.
Runs end-to-end JTBD workflow for AsciiDoc repos with master.adoc: analyze JTBD records, generate TOC, compare structures, produce consolidation reports. Batch processing supported.
Analyzes feature requests, maintains PRDs, and decomposes into tracks with work breakdowns and execution order. For new feature planning, architecture changes, requirements analysis, or plan adjustments.
Generates structured Markdown task briefs at docs/briefs/ from notes or descriptions, with sections keyed to Conventional Commits types to guide coding agents (e.g., refactor preserves, fix reproduces). Briefset mode creates parent plus child briefs for multi-context tasks.
Share bugs, ideas, or general feedback.
Generate a standalone, high-quality Jobs-To-Be-Done Table of Contents from JTBD analysis records.
# From analysis directory
/jtbd-toc analysis/rhoai/creating-a-workbench/
# From specific JSONL file
/jtbd-toc analysis/rhoai/creating-a-workbench/creating-a-workbench-jtbd.jsonl
toc-guidelines.md<doc>-toc-new_taxonomy.mdTOC is saved to:
analysis/<project>/<doc>/<doc>-toc-new_taxonomy.md
The generated TOC follows this structure (see toc-guidelines.md for details):
# [Guide Name]
**Jobs-To-Be-Done Oriented Table of Contents**
*Organized by user goals and workflow stages*
---
## Guide Overview
**Purpose:** [One sentence - what this guide helps users accomplish]
**Personas:** [List all personas from the data]
**Main Jobs:** [Number] core jobs across [Number] workflow stages
## Quick Navigation
**I want to:**
- [Common goal 1] -> Job X (Stage)
- [Common goal 2] -> Job Y (Stage)
...
# Table of Contents
## Choose Your Approach
### Job 1: [Clean Main Job Title]
*When [situation from job statement]*
**Personas:** [Who does this job]
[Organized content with options/paths]
## Set Up & Configure
### Job 2: [Next Main Job]
...
## Deploy & Use
...
## Track Performance
...
## Appendices
### A. Platform Comparison Matrix
[Trade-offs between options]
### B. Method Decision Guide
[Complexity, repeatability, prerequisites]
### C. Workflow Coverage Analysis
| Stage | Coverage | Jobs |
|-------|----------|------|
| Get Started | ✅ | Job 1 |
| Configure | ✅ | Jobs 2-4 |
| Deploy | ✅ | Jobs 5-7 |
| Monitor | ❌ | - |
...
## Navigation Guide
...
## Document Statistics
...
Jobs MUST be numbered sequentially (1, 2, 3, 4...) based on the order they appear in the TOC output:
Correct:
### Job 1: Understand Architecture
### Job 2: Choose Update Channel
### Job 3: Verify Requirements
### Job 4: Configure Namespaces
Formula: [Verb] + [Object/Outcome]
Good examples:
Bad examples:
Use natural headings, NOT methodology jargon:
| Internal Stage | Use This Heading |
|---|---|
| Get Started | "Getting Started" |
| Plan | "Choose Your Approach" or "Understand Options" |
| Architecture | "Understand Architecture" |
| Configure | "Set Up & Configure" |
| Deploy | "Deploy & Use" |
| Develop | "Develop & Experiment" |
| Training | "Train Models" |
| Operate | "Operate & Manage" |
| Monitor | "Track Performance" |
| Analyze | "Analyze Results" |
| Observe | "Observe System State" |
| Troubleshoot | "Troubleshoot Issues" |
| Administer | "Administer Platform" |
| Secure | "Secure Your Environment" |
| Migrate | "Migrate & Move" |
| Upgrade | "Upgrade & Update" |
| Extend | "Extend & Customize" |
| Reference | "Reference" |
| What's New | "What's New" |
Structure every job using:
Job (Outcome)
└── User Story / Themed Goal (Approach)
└── Task (Implementation step)
Only add enrichment when data warrants it:
| Element | Include When... |
|---|---|
| Timing: | Job MUST happen before/after another, OR action is irreversible |
| Requires: | Prerequisites are non-obvious (not just "admin access") |
| Why: | Risk/motivation changes how users approach the job |
Most jobs will NOT have these lines - keep entries minimal by default.
### Job [Number]: [Clean Title]
*When [situation]*
**Personas:** [Who does this]
**Timing:** [ONLY if critical] - BEFORE Job X - [consequence if missed]
**Requires:** [ONLY if non-obvious] [Brief prerequisite list]
#### [Descriptive heading for options/paths]
**[If choice-based]:**
- **Option A: [Name]** ([When to use])
*Persona: [If specific]*
→ Lines X-Y: Section Name
Source: Chapter X, Section X.X
- [Benefit/feature]
- **Option B: [Name]** ([When to use])
→ Lines A-B: Section Name
Source: Chapter X, Section X.X
**[If persona-based]:**
- **For [Persona]: [Approach]**
→ Lines X-Y: Section Name
Source: Chapter X, Section X.X
- **For [Other Persona]: [Different Approach]**
→ Lines A-B: Section Name
Source: Chapter X, Section X.X
Format:
→ Lines X-Y: Section Title
Source: Chapter X, Section X.X
Examples:
→ Lines 19-22: Preface
Source: Front matter
→ Lines 35-42: Storage requirements
Source: Chapter 1, Section 1.2
→ Lines 488-683: Installing by using the CLI
Source: Chapter 3, Section 3.1
Rules:
Source: line with chapter/section for writer navigationDon't list tasks flatly. Group under themed user stories:
| Instead of... | Use... |
|---|---|
| Flat list of 10 configuration tasks | 3-4 themed groups |
| "Configure X", "Configure Y", "Configure Z" | "Security Hardening", "Core Profile", "Integrations" |
Verification is a final step within execution jobs, NOT a sibling job:
Wrong:
### Job 4: Deploy Workbench
### Job 5: Verify Deployment <- WRONG: Sibling job
Right:
### Job 4: Provision Workbench Environment
#### 4.1 Define Core Profile
[Tasks...]
#### 4.2 Verify Provisioning (Confirmation Step) <- RIGHT: Final step
When multiple "tasks" are fields in a single YAML, present as configuration inputs:
Wrong: Implies 5 separate operations
#### 2.4 Configure OAuth
#### 2.5 Configure Resources
#### 2.6 Attach Data Connections
Right: One action with multiple inputs
#### 2.2 Define Workbench Configuration
**Goal:** Author the Notebook CRD manifest.
- **Input:** OAuth authentication
- **Input:** Resource limits
- **Input:** Data connections
#### 2.3 Apply and Verify
- **Task:** `oc apply -f notebook.yaml`
→ Lines X-Y: Section Title format# Step 1: Ensure JTBD records exist
ls analysis/rhoai/creating-a-workbench/creating-a-workbench-jtbd.jsonl
# Step 2: Generate TOC
/jtbd-toc analysis/rhoai/creating-a-workbench/
# Output:
# - Displays TOC preview
# - Writes to analysis/rhoai/creating-a-workbench/creating-a-workbench-toc-new_taxonomy.md
# Step 3: Review and compare
cat analysis/rhoai/creating-a-workbench/creating-a-workbench-toc-new_taxonomy.md
/jtbd-compare docs_raw/rhoai/creating-a-workbench.md
For complete TOC generation guidelines, see toc-guidelines.md in this skill directory.