From 445b46ad65f98f2e34928eaf9340d5417edcde79 Mon Sep 17 00:00:00 2001 From: darthrootbeer Date: Thu, 1 Oct 2026 22:21:40 -0400 Subject: [PATCH 1/5] fix(docs-pipeline): make it run from a fresh clone and remove private setup Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01XV3Ggh86cf2xwUyz28XaN6 --- pipelines/docs-pipeline/ARCHITECTURE.md | 19 +-- pipelines/docs-pipeline/README.md | 20 ++- pipelines/docs-pipeline/SETUP.md | 126 +++++++++++---- pipelines/docs-pipeline/_knowledge/README.md | 8 +- .../docs-pipeline/_knowledge/glossary.yaml | 10 +- .../_knowledge/product-kb/domain-models.md | 30 ++++ .../_knowledge/product-kb/endpoints.md | 23 +++ .../_knowledge/product-kb/error-codes.md | 15 ++ .../_knowledge/product-kb/index.md | 32 ++++ .../product-kb/integration-types.md | 18 +++ .../_knowledge/product-kb/recent-changes.md | 14 ++ .../_knowledge/product-kb/webhooks.md | 17 ++ .../style-guide_api-reference.md | 36 ++--- .../style-guides/diagrams/README.md | 2 +- .../diagrams/style-guide_diagrams.md | 50 +++--- .../style-guides/diataxis/README.md | 2 +- .../style-guide_diataxis-type_explanation.md | 32 ++-- ...style-guide_diataxis-type_how-to-guides.md | 4 +- .../style-guide_diataxis-type_reference.md | 12 +- .../style-guide_guide-set-overview.md | 20 +-- .../_knowledge/style-guides/general/README.md | 4 +- .../general/style-guide_general.md | 54 +++---- .../style-guides/illustrations/README.md | 2 +- .../_knowledge/style-guides/images/README.md | 2 +- .../docs-pipeline/docs-diataxis-audit.md | 28 ++-- .../docs-diataxis-create-overview.md | 10 +- .../docs-pipeline/docs-diataxis-split.md | 30 ++-- .../docs-pipeline/docs-grammar-spelling.md | 2 +- pipelines/docs-pipeline/docs-links-review.md | 4 +- pipelines/docs-pipeline/docs-pipeline.md | 28 +++- pipelines/docs-pipeline/docs-publish.md | 16 +- pipelines/docs-pipeline/docs-sme-review.md | 12 +- .../docs-pipeline/docs-style-check-human.md | 8 +- .../docs-style-check-structure.md | 4 +- .../docs-pipeline/docs-style-check-voice.md | 4 +- .../docs-pipeline/docs-visuals-review.md | 20 +-- pipelines/docs-pipeline/docs-work-verify.md | 4 +- .../docs-pipeline/docs-workspace-setup.md | 146 ++++++++---------- .../sample/acme-orders-cancellations.md | 35 +++++ .../workspace-gitignore.template | 25 +++ skills/docs-readability-check/README.md | 91 +++++++++++ 41 files changed, 696 insertions(+), 323 deletions(-) create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/domain-models.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/endpoints.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/error-codes.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/index.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/integration-types.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/recent-changes.md create mode 100644 pipelines/docs-pipeline/_knowledge/product-kb/webhooks.md create mode 100644 pipelines/docs-pipeline/sample/acme-orders-cancellations.md create mode 100644 pipelines/docs-pipeline/workspace-gitignore.template create mode 100644 skills/docs-readability-check/README.md diff --git a/pipelines/docs-pipeline/ARCHITECTURE.md b/pipelines/docs-pipeline/ARCHITECTURE.md index 83f3a59..044aa11 100644 --- a/pipelines/docs-pipeline/ARCHITECTURE.md +++ b/pipelines/docs-pipeline/ARCHITECTURE.md @@ -14,7 +14,7 @@ Think of it like a car wash with stations: soap, rinse, wax, dry. You don't skip Each stage is a **skill** — a markdown file full of instructions that Claude Code reads and follows. When you type `/docs-diataxis-audit`, Claude loads that skill file and executes the steps inside it. The skill tells Claude what to look at, what to produce, and what to check before moving on. -Skills are just text files. They live in `~/.claude/skills/`. You can read them, edit them, and version them like any other file. +Skills are just text files. They live in `~/.claude/skills//SKILL.md` once installed (section 3 of [SETUP.md](./SETUP.md) has the exact install loop). You can read them, edit them, and version them like any other file. --- @@ -24,15 +24,15 @@ Three knowledge files live in `_knowledge/` and are loaded by accuracy-sensitive - `_knowledge/glossary.yaml` — domain terminology loaded by `docs-grammar-spelling` to check canonical forms and catch common mistakes - `_knowledge/product-kb/` — product model files loaded by `docs-sme-review` to fact-check domain accuracy claims -- `_knowledge/style-guides/style-guide.md` — voice and tone rules loaded by `docs-style-check-voice` +- `_knowledge/style-guides/` — style guides loaded by the style passes. `docs-style-check-voice` reads `general/style-guide_general.md`; the structure and human passes read the `diataxis/` and `write-like-a-human/` folders -Placeholder files with instructions are in `_knowledge/`. The pipeline will run without them, but Stage 3b (voice), Stage 3e (grammar), and Stage 4c (SME review) will produce generic or incomplete results. +Starter files with instructions are in `_knowledge/`, so the pipeline runs from a fresh clone. The product knowledge base describes a made-up product (the "Acme Orders API") and must be replaced with your own: until then Stage 4c (SME review) checks drafts against the wrong product. Stage 0 copies `_knowledge/` into each workspace, because the skills read it relative to the workspace folder. --- ## The workspace -Before anything runs, the pipeline creates a **workspace** — a folder in `~/projects/` named like `workspace_doc-1319_setup-and-credentials`. This is where everything lives: +Before anything runs, the pipeline creates a **workspace** — a folder in `~/projects/` (the `WORKSPACE_ROOT` constant) named like `workspace_doc-1319_setup-and-credentials`. This is where everything lives: ``` workspace_doc-1319_setup-and-credentials/ @@ -43,7 +43,8 @@ workspace_doc-1319_setup-and-credentials/ _process/ ← audit reports, style notes, review outputs, changes log CLAUDE.md ← instructions for Claude working in this project README.md - _shared/ ← symlink to shared tools and style guides + _knowledge/ ← copy of the glossary, style guides and product knowledge base + _shared/ ← optional link to your own shared tools (only if SHARED_CONFIG_DIR is set) ``` The workspace is a git repo. Every stage commits its output. So you can always see exactly what changed at each step. @@ -111,7 +112,7 @@ flowchart TD ### Stage 0 — Workspace Setup (`/docs-workspace-setup`) -Creates the project directory (`workspace_doc-{num}_{slug}`), runs `git init`, adds shared resource symlinks, writes `CLAUDE.md` and `README.md`, and copies the source doc(s) into `docs/input/`. Optionally creates a project note in your tracking tool. +Creates the project directory (`workspace_doc-{num}_{slug}`), runs `git init`, copies in `_knowledge/`, writes `CLAUDE.md`, `README.md` and `.gitignore`, and copies the source doc(s) into `docs/input/`. Optionally links a shared config folder and creates a project note in your notes folder. **Outputs:** Project directory, initial git commit, source docs in place. @@ -132,8 +133,8 @@ Most docs mix types. The audit surfaces those mixtures and recommends whether to **Outputs:** - `{guide}_audit-report.md` — full analysis with section-level breakdown -- `{guide}_mapping.json` — machine-readable section map (schema: `_shared/schemas/diataxis-audit-mapping/`) -- SVG visualizations of the content distribution +- `{guide}_mapping.json` — machine-readable section map (structure is described in the audit skill; an optional schema in your shared config folder is used if present) +- SVG visualizations of the content distribution (optional, only if the diagram tool in your shared config folder is installed) --- @@ -155,7 +156,7 @@ Five sequential passes. Each one loads what it needs fresh. Each pass edits docs Checks Diataxis structural rules for each doc's type: required sections, heading format, opening sentence, conclusion. Rules differ per type — a how-to has different required sections than a reference. **3b — Voice (`/docs-style-check-voice`)** -Reads the style guide from `_knowledge/style-guides/style-guide.md`. Populate this with your team's conventions before running. Applies voice and tone, list formatting, callout usage, table structure, terminology, and addressing conventions (`you`, not `the user`). +Reads the style guide from `_knowledge/style-guides/general/style-guide_general.md`. Adapt it to your team's conventions before running. Applies voice and tone, list formatting, callout usage, table structure, terminology, and addressing conventions (`you`, not `the user`). **3c — Human (`/docs-style-check-human`)** Removes AI writing patterns: em dashes, banned filler phrases (`it's worth noting`, `notably`), uniform sentence length, bold-label lists, corporate padding. diff --git a/pipelines/docs-pipeline/README.md b/pipelines/docs-pipeline/README.md index 42e1bc2..eea0f63 100644 --- a/pipelines/docs-pipeline/README.md +++ b/pipelines/docs-pipeline/README.md @@ -13,7 +13,7 @@ Each skill is a markdown file that Claude Code loads when you run the matching ` | File | Slash command | Stage | What it does | |------|--------------|-------|--------------| | `docs-pipeline.md` | `/docs-pipeline` | Orchestrator | Runs the full pipeline end-to-end, stage by stage | -| `docs-workspace-setup.md` | `/docs-workspace-setup` | 0 | Creates the workspace directory, symlinks, and project note | +| `docs-workspace-setup.md` | `/docs-workspace-setup` | 0 | Creates the workspace directory, copies in the knowledge files, and writes the starter files | | `docs-diataxis-audit.md` | `/docs-diataxis-audit` | 1 | Classifies doc content by Diataxis type, produces audit report + JSON mapping | | `docs-diataxis-split.md` | `/docs-diataxis-split` | 2 | Extracts content into typed output files (how-to, explanation, reference, tutorial) | | `docs-diataxis-create-overview.md` | `/docs-diataxis-create-overview` | 2b | Creates the overview/index entry-point doc after a split | @@ -30,17 +30,23 @@ Each skill is a markdown file that Claude Code loads when you run the matching ` | `docs-publish.md` | `/docs-publish` | 6 | Copies output to docs repo, adds frontmatter, creates branch + PR | | `docs-work-verify.md` | `/docs-work-verify` | Post | Verifies the PR merged and changes are live | +## Quick start + +1. Install the skills with the loop in section 3 of [SETUP.md](./SETUP.md). +2. Run the smoke test in section 4 of [SETUP.md](./SETUP.md). It uses the sample doc in [`sample/`](./sample/acme-orders-cancellations.md) and needs no configuration. +3. Replace the made-up product knowledge in `_knowledge/` with your own (next section), then fill in the placeholders under Configuration. + ## Knowledge sources -The pipeline loads three knowledge sources at runtime. Populate these before running: +The pipeline loads three knowledge sources at runtime. They ship as working starters, so it runs from a fresh clone. The product knowledge base describes a made-up product (the "Acme Orders API"), so replace it with your own before you trust Stage 4c on real docs: | Path | What it needs | |------|--------------| | `_knowledge/glossary.yaml` | Your domain terminology, canonical forms, and common mistakes | | `_knowledge/product-kb/` | Your product model: integration types, API endpoints, domain objects, webhooks, error codes | -| `_knowledge/style-guides/style-guide.md` | Your voice, tone, and formatting rules | +| `_knowledge/style-guides/general/style-guide_general.md` | Your voice, tone, and formatting rules | -Placeholder files with structure and instructions are already in `_knowledge/`. Fill them in before running `docs-grammar-spelling`, `docs-sme-review`, or `docs-style-check-voice`. +Each file has fill-in instructions at the top. Stage 0 copies the whole `_knowledge/` folder into every new workspace, so fill these in before you create one. ## Pipeline order @@ -81,6 +87,8 @@ Before using this pipeline on your docs, replace these placeholders throughout t | `{YOUR_DOCS_REPO_PATH}` | Local filesystem path to your docs repo clone | | `{YOUR_DEFAULT_OG_IMAGE_URL}` | Default Open Graph image URL for published docs | +Two placeholders are optional. `{SHARED_CONFIG_DIR}` (a folder of your own shared tools) and `{NOTES_DIR}` (a notes folder for a project note) can stay as they are: any step that needs them is skipped. `{YOUR_PIPELINE_DIR}` is filled in by the install loop in SETUP.md, so you do not set it by hand. + --- ### Prompt for your AI model @@ -94,10 +102,10 @@ I have attached the README for "docs-pipeline", a set of Claude Code skills that 1. In plain language, say what problem it solves and what it does not do. 2. List the stages in order, one line each, and explain why the style passes come before the reviews. -3. Say where a person has to decide something and where the AI works alone. +3. Say exactly what the person does between every two stages, and what the AI does alone inside a stage. 4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. -A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead, and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README. +A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead (so it never says the person does not touch a stage), and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README. ``` **Review against your own setup** diff --git a/pipelines/docs-pipeline/SETUP.md b/pipelines/docs-pipeline/SETUP.md index 54e80c2..9423a21 100644 --- a/pipelines/docs-pipeline/SETUP.md +++ b/pipelines/docs-pipeline/SETUP.md @@ -21,7 +21,9 @@ Before running any skill: ## 2. Configuration — replace all placeholders -Every skill file contains placeholder values in `{CURLY_BRACES}`. Replace them before running any skill. Do a find-and-replace across all `.md` files in this directory. +Every skill file contains placeholder values in `{CURLY_BRACES}`. Replace the ones you need before you install the skills in section 3 (the install step copies the files, so a change made later needs a re-install). Do a find-and-replace across all `.md` files in this directory. + +Which placeholders you need depends on the stages you use. The smoke test in section 4 needs none of them. Stages 4b (links), 4c (the naming-collision part only), 6 (publish) and the post-merge check need the docs-repo placeholders. | Placeholder | What it is | Example | |-------------|-----------|---------| @@ -34,23 +36,83 @@ Every skill file contains placeholder values in `{CURLY_BRACES}`. Replace them b | `{YOUR_USERNAME}` | Git username for branch naming | `jsmith` | | `{YOUR_DEFAULT_OG_IMAGE_URL}` | Default Open Graph image for published pages | `https://cdn.acme.com/og-default.png` | -**One-liner to find all remaining placeholders after replacement:** +Three more placeholders are optional. Leave them as they are unless you want the feature: + +| Placeholder | What it is | If you leave it unset | +|-------------|-----------|-----------------------| +| `{SHARED_CONFIG_DIR}` | A folder of your own shared tools (for example a JSON schema or a diagram generator) | The steps that need it are skipped | +| `{NOTES_DIR}` | A notes folder (for example an Obsidian vault) where Stage 0 writes a project note | No project note is written | +| `{YOUR_PIPELINE_DIR}` | The path of this folder | You do not set this by hand: the install loop in section 3 fills it in | + +**One-liner to find all remaining `{YOUR_` placeholders**, run from inside this folder: ```bash -grep -r '{YOUR_' ~/Downloads/docs-pipeline/ --include="*.md" -l +grep -rl '{YOUR_' . --include='*.md' ``` +`{YOUR_PIPELINE_DIR}` will still show up in the source files. That is expected: it is filled in on the installed copies, not here. + --- -## 3. Knowledge sources — build before running +## 3. Install the skills + +Claude Code loads a skill from `//SKILL.md`. The files in this folder are flat (`docs-pipeline.md`, `docs-sme-review.md`, ...), so copying the folder as it is will not register them. This loop makes one folder per skill and fills in `{YOUR_PIPELINE_DIR}` on the way. + +Run it from inside this folder (`pipelines/docs-pipeline/` in your clone of the repo): + +```bash +PIPELINE_DIR="$PWD" +SKILLS_DIR="$HOME/.claude/skills" # use ./.claude/skills instead to install for one project only + +for f in docs-*.md; do + name="${f%.md}" + mkdir -p "$SKILLS_DIR/$name" + sed "s|{YOUR_PIPELINE_DIR}|$PIPELINE_DIR|g" "$f" > "$SKILLS_DIR/$name/SKILL.md" +done + +# the readability stage (3d) lives in the repo's skills/ folder +mkdir -p "$SKILLS_DIR/docs-readability-check" +cp ../../skills/docs-readability-check/SKILL.md "$SKILLS_DIR/docs-readability-check/SKILL.md" +``` + +This installs 17 skills: the 16 `docs-*.md` files here plus `docs-readability-check`. Run it again any time you edit a file. Keep your clone where it is: the skills read `_knowledge/` and `workspace-gitignore.template` from `PIPELINE_DIR`. + +**Check that they registered.** Start a new Claude Code session and type `/docs-`. The list should show all 17 names. Or run this from the shell and count the lines (it should print 17): + +```bash +claude -p "hi" --model haiku --output-format stream-json --verbose | grep -o '"docs-[a-z-]*"' | sort -u | wc -l +``` -Three knowledge sources live in `_knowledge/`. They are loaded by the accuracy-sensitive pipeline stages. The pipeline will run without them, but Stages 3b, 3e, and 4c will produce shallow or incorrect results. +If the count is lower, the loop wrote to a different folder than the one Claude Code reads: check `SKILLS_DIR`, and start a fresh session. + +--- + +## 4. Smoke test + +This runs the pipeline on a short sample doc that ships in this folder (`sample/acme-orders-cancellations.md`, a made-up doc about a made-up product). It stops before anything is published and needs no placeholders. Run these in Claude Code: + +1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. +2. In that folder, copy the sample in: `cp "/sample/acme-orders-cancellations.md" docs/output/docs/` +3. `/docs-style-check-voice docs/output/docs/` (Stage 3b). It edits the sample in place and writes a report to `docs/output/_process/style-audit/`. +4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `_process/sme-review/acme-orders-cancellations-sme-review.md`. + +**What proves it worked.** Stage 3b does not stop with "Style guide not found". The sample has a casual opener, so the voice report lists at least one tone fix. Stage 4c does not stop with "Product KB not found". Its report lists at least these three HIGH domain findings, because the sample contradicts `_knowledge/product-kb/`: a paid order cannot be canceled, the hosted order form does not receive webhooks, and the rate limit is 100 a minute, not a thousand. + +**Undo.** Delete the folder `~/projects/workspace_doc-1_smoke-test/`. Nothing else was changed. + +--- + +## 5. Knowledge sources — build before running + +Three knowledge sources live in `_knowledge/`. They are loaded by the accuracy-sensitive pipeline stages. Each one ships as a working starter, so the pipeline runs from a fresh clone. The glossary and style guides are generic. The product knowledge base describes a made-up product (the "Acme Orders API") and must be replaced with your own before Stages 3e and 4c mean anything on real docs. + +Stage 0 copies `_knowledge/` into every new workspace, so fill these files in once, in this folder, before you create workspaces. A workspace made earlier keeps its old copy. Populate all three before running a full pipeline on any real docs. --- -### 3.1 Glossary — `_knowledge/glossary.yaml` +### 5.1 Glossary — `_knowledge/glossary.yaml` **Loaded by:** `docs-grammar-spelling` (Stage 3e) @@ -68,13 +130,13 @@ Then translate each answer into a glossary entry following the YAML structure in --- -### 3.2 Product knowledge base — `_knowledge/product-kb/` +### 5.2 Product knowledge base — `_knowledge/product-kb/` **Loaded by:** `docs-sme-review` (Stage 4c) **What it does:** The SME review skill loads these files and fact-checks every claim in the draft docs against your actual product model — integration type scopes, API resource availability, webhook event mappings, error code meanings. It flags content that would mislead a customer following the docs. -**Files and what to put in each:** +**Files and what to put in each.** All seven files ship as starters with fill-in instructions at the top and a few fictional example rows (marked `FICTIONAL EXAMPLE DATA`). Delete the example rows and add yours: | File | Minimum viable content | |------|----------------------| @@ -108,17 +170,17 @@ For `recent-changes.md`: --- -### 3.3 Style guide — `_knowledge/style-guides/style-guide.md` +### 5.3 Style guide — `_knowledge/style-guides/general/style-guide_general.md` **Loaded by:** `docs-style-check-voice` (Stage 3b) **What it does:** The voice skill reads every rule in this file and applies them to the draft docs — rewriting prose that violates voice, tone, list formatting, callout syntax, and addressing conventions. -**Minimum viable:** The placeholder file already contains a working baseline (imperative steps, sentence-case headings, "you" for the reader, no marketing language, numbered lists with lead-ins and outcome sentences). This is enough to run Stage 3b on any docs. +**Minimum viable:** The shipped file already contains a working baseline (imperative steps, sentence-case headings, "you" for the reader, no marketing language, numbered lists with lead-ins and outcome sentences). Its examples use the made-up Acme Orders product. This is enough to run Stage 3b on any docs. Stages 3a, 3c and the Diataxis audit read the other folders under `_knowledge/style-guides/` the same way. **To make it yours:** Add or override rules for your specific conventions. Common additions: - Product name capitalization and formatting -- Preferred terminology for your domain ("customers" vs. "developers" vs. "merchants") +- Preferred terminology for your domain ("customers" vs. "developers" vs. "clients") - Callout syntax for your docs platform (if different from the ReadMe defaults in the baseline) - Any structural patterns your team has agreed on (e.g. always include a Prerequisites section) @@ -134,7 +196,7 @@ I have attached the setup guide for "docs-pipeline" and its placeholder file `_k [PASTE two or three paragraphs from your docs that use your product's own terms.] -Following section 3.1 of the guide and the structure in the placeholder file, draft a first `glossary.yaml` with the 10 most important terms from my text. For every entry give the canonical form, the aliases only if my text shows them, and the docs_facing flag. Where my text does not show a capitalization rule or a common mistake, leave that field out and write "needs review" instead of inventing one. Do not infer a capitalization rule from how a word happens to be capitalized in my text. +Following section 5.1 of the guide and the structure in the placeholder file, draft a first `glossary.yaml` with the 10 most important terms from my text. For every entry give the canonical form, the aliases only if my text shows them, and the docs_facing flag. Where my text does not show a capitalization rule or a common mistake, leave that field out and write "needs review" instead of inventing one. Do not infer a capitalization rule from how a word happens to be capitalized in my text. A good answer uses the field names from the placeholder file exactly, has no more than 10 entries, and marks everything it could not know as "needs review". ``` @@ -143,7 +205,7 @@ A good answer uses the field names from the placeholder file exactly, has no mor --- -## 4. Running the pipeline +## 6. Running the pipeline ### Full pipeline @@ -153,17 +215,17 @@ A good answer uses the field names from the placeholder file exactly, has no mor Example: ``` -/docs-pipeline TICKET-1234 payment-methods +/docs-pipeline TICKET-1234 order-cancellations ``` -The pipeline creates a workspace at `~/projects/workspace_doc-1234_payment-methods/`, copies the source doc(s) into `docs/input/`, and walks through each stage. It pauses between stages and asks to proceed. You can say `proceed`, `skip`, `stop`, or `redo`. +The pipeline creates a workspace at `~/projects/workspace_doc-1234_order-cancellations/`, copies the source doc(s) into `docs/input/`, and walks through each stage. It pauses between stages and asks to proceed. You can say `proceed`, `skip`, `stop`, or `redo`. ### Individual skills Any skill can be run standalone on a file or folder: ``` -/docs-diataxis-audit docs/input/payment-methods.md +/docs-diataxis-audit docs/input/order-cancellations.md /docs-style-check-human docs/output/docs/ /docs-sme-review docs/output/docs/ TICKET-1234 ``` @@ -187,21 +249,24 @@ Any skill can be run standalone on a file or folder: --- -## 5. Skill-to-knowledge dependency map +## 7. Skill-to-knowledge dependency map | Skill | Knowledge file(s) loaded | If missing or empty | |-------|--------------------------|---------------------| -| `docs-style-check-voice` | `_knowledge/style-guides/style-guide.md` | Skill stops: "Style guide not found" | +| `docs-style-check-voice` | `_knowledge/style-guides/general/style-guide_general.md` | Skill stops: "Style guide not found" | | `docs-grammar-spelling` | `_knowledge/glossary.yaml` | Skill stops: "Glossary not found" | | `docs-sme-review` | `_knowledge/product-kb/index.md` + relevant sub-files | Skill stops: "Product KB not found" | -| `docs-diataxis-audit` | None | Runs fully on built-in Diataxis knowledge | +| `docs-diataxis-audit` | `_knowledge/style-guides/diataxis/README.md` | Skill stops if the framework file is missing | +| `docs-style-check-structure` | `_knowledge/style-guides/diataxis/` | Skill stops: "Style guide not found" | +| `docs-style-check-human` | `_knowledge/style-guides/write-like-a-human/` | Skill stops: "Style guide not found" | | `docs-diataxis-split` | Audit report + JSON mapping from Stage 1 | Requires Stage 1 output | | `docs-links-review` | Live docs corpus (cloned from `{YOUR_DOCS_REPO}`) | Stops if clone fails | +| `docs-sme-review` naming-collision check | Live docs corpus (same clone) | Skipped with a note, the rest of the review runs | | All others | None | Run without external knowledge sources | --- -## 6. Keeping knowledge current +## 8. Keeping knowledge current | File | Update when | How to know it's stale | |------|------------|----------------------| @@ -213,24 +278,25 @@ Any skill can be run standalone on a file or folder: | `product-kb/error-codes.md` | New error code; code meaning changed | SME review flags error handling sections | | `product-kb/webhooks.md` | New event; event renamed; payload changed | SME review flags webhook sections | | `product-kb/recent-changes.md` | Continuous — update as changes ship; clear entries older than 90 days | This file is meant to be a rolling window, not a permanent log | -| `style-guides/style-guide.md` | Style decision changes; new convention agreed; platform callout syntax changes | Voice audit flags the same pattern as wrong repeatedly | +| `style-guides/general/style-guide_general.md` | Style decision changes; new convention agreed; platform callout syntax changes | Voice audit flags the same pattern as wrong repeatedly | When you update any `product-kb/` file, update the `extracted:` date in `product-kb/index.md`. --- -## 7. Troubleshooting +## 9. Troubleshooting | Error | Cause | Fix | |-------|-------|-----| -| `Style guide not found at _knowledge/style-guides/style-guide.md` | File missing or path wrong | Check `STYLE_GUIDE` constant in `docs-style-check-voice.md` | +| `Style guide not found at _knowledge/style-guides/general/style-guide_general.md` | You are not running from inside a workspace, or the workspace has no `_knowledge/` copy | Run from the workspace folder, or copy `_knowledge/` into it. Check the `STYLE_GUIDE` constant in `docs-style-check-voice.md` | | `Glossary not found at _knowledge/glossary.yaml` | File missing or path wrong | Check `GLOSSARY` constant in `docs-grammar-spelling.md` | -| `Product KB not found at _knowledge/product-kb/` | `index.md` missing | Populate `_knowledge/product-kb/index.md` | +| `Product KB not found at _knowledge/product-kb/` | You are not running from inside a workspace, or the workspace has no `_knowledge/` copy | Run from the workspace folder, or copy `_knowledge/` into it | +| `PIPELINE_DIR is not set` | The skills were copied without the install loop | Re-run the loop in section 3 | | `Failed to clone docs repo` | `gh` not authenticated or repo name wrong | Run `gh auth login`; check `{YOUR_ORG}/{YOUR_DOCS_REPO}` | | `No output docs found in docs/output/docs/` | Split hasn't run yet | Run Stage 2 first | | `Branch already exists` | Previous partial run | Delete the branch: `git branch -D {branch-name}` | | `Product KB last extracted >90 days ago` | Staleness warning, not a stop | Update KB files and refresh `extracted:` date in `index.md` | -| Placeholders like `{YOUR_ORG}` still appearing in output | Configuration incomplete | Run the grep one-liner from Section 2 to find remaining placeholders | +| Placeholders like `{YOUR_ORG}` still appearing in output | Configuration incomplete | Run the grep one-liner from section 2 to find remaining placeholders | --- @@ -247,7 +313,7 @@ I have attached the setup guide for "docs-pipeline". Teach it to me as if I am a 2. Say which steps I can skip for a first trial and which I cannot. 3. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. -A good answer follows the guide's order, covers the prerequisites, the placeholders, the knowledge sources, and running the pipeline, and does not add a step the guide does not contain. +A good answer follows the guide's order, covers the prerequisites, the placeholders, the install loop, the smoke test, the knowledge sources, and running the pipeline, and does not add a step the guide does not contain. ``` **Review against your own setup** @@ -265,11 +331,13 @@ A good answer has one line per prerequisite, never marks something as met withou **Adapt and test** ```text -I have attached the setup guide for "docs-pipeline". I want to run the smallest possible test before I use it on real documentation. +I have attached the setup guide for "docs-pipeline". Section 4 is a smoke test on a sample doc. I want to run the same test on one of my own short docs instead. + +[PASTE the file name of your doc and a one-line description of what it is about.] -Write me a smoke test that uses one short markdown file and stops before anything is published. Say which placeholders in section 2 I can fill with dummy values for this test and which need real values, following the guide's own rule about placeholders. List the exact commands, what proves the test worked, and how to undo everything afterwards. Use only commands that appear in the guide. Where the guide has no command for something, say so and do not write one. +Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly instead of promising a result. -A good answer respects what the guide says about replacing placeholders, uses only commands the guide contains, stops before the publish stage, and says so where the guide does not give an undo step. +A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them. ``` **How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". diff --git a/pipelines/docs-pipeline/_knowledge/README.md b/pipelines/docs-pipeline/_knowledge/README.md index a8f1ec7..67d73f5 100644 --- a/pipelines/docs-pipeline/_knowledge/README.md +++ b/pipelines/docs-pipeline/_knowledge/README.md @@ -14,7 +14,9 @@ This folder holds the knowledge sources the pipeline skills load at runtime. Pop | `product-kb/error-codes.md` | `docs-sme-review` | Error codes and their meanings | | `product-kb/webhooks.md` | `docs-sme-review` | Webhook events, payloads, and integration scopes | | `product-kb/recent-changes.md` | `docs-sme-review` | Recent API changes that may affect existing docs | -| `style-guides/style-guide.md` | `docs-style-check-voice` | General voice, tone, and formatting rules for your docs | +| `style-guides/general/style-guide_general.md` | `docs-style-check-voice` | General voice, tone, and formatting rules for your docs | +| `style-guides/diataxis/` | `docs-diataxis-audit`, `docs-style-check-structure` | Diataxis framework and per-type structure rules | +| `style-guides/write-like-a-human/` | `docs-style-check-human` | Rules for removing machine-written patterns | ## Keeping knowledge current @@ -22,4 +24,6 @@ The SME review skill checks the `extracted:` frontmatter date on `product-kb/ind ## Note on this copy of the pipeline -The `product-kb/` files listed above are intentionally not included in this repo — they hold a specific product's proprietary API surface and domain model, which is exactly the kind of content this knowledge folder is designed to hold *for your own project*, not something to ship generically. Populate `product-kb/` with your own product's equivalent before running `docs-sme-review`. Everything else in this folder (the glossary, the style guides) is generic and ready to use or adapt. +Every file here is a working starter. The `product-kb/` files describe a made-up product, the "Acme Orders API" with orders, customers and invoices, and are marked `FICTIONAL EXAMPLE DATA`. They are there so the pipeline runs end to end on the sample doc in `../sample/`. Replace the example rows with facts about your own product before you run `docs-sme-review` on real docs. The glossary and the style guides are generic: their examples use the same made-up product, and every rule applies to any API docs. + +Stage 0 (`/docs-workspace-setup`) copies this whole folder into each new workspace, because the skills read `./_knowledge/` relative to the workspace. diff --git a/pipelines/docs-pipeline/_knowledge/glossary.yaml b/pipelines/docs-pipeline/_knowledge/glossary.yaml index bc0e42a..86880cd 100644 --- a/pipelines/docs-pipeline/_knowledge/glossary.yaml +++ b/pipelines/docs-pipeline/_knowledge/glossary.yaml @@ -50,12 +50,12 @@ terms: # Add your product-specific terms below this line. # Example: # - # - canonical: PaymentIntent + # - canonical: OrderDraft # docs_facing: true # aliases: - # - payment intent - # - payment-intent + # - order draft + # - order-draft # usage: - # capitalization: PascalCase when referring to the API object. Lowercase in generic prose ("the payment intent was created"). + # capitalization: PascalCase when referring to the API object. Lowercase in generic prose ("the order draft was created"). # mistakes: - # - '"payment intent"' → '"PaymentIntent"': Use PascalCase for the API object name. + # - '"order draft"' → '"OrderDraft"': Use PascalCase for the API object name. diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/domain-models.md b/pipelines/docs-pipeline/_knowledge/product-kb/domain-models.md new file mode 100644 index 0000000..bd4b43c --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/domain-models.md @@ -0,0 +1,30 @@ +# Domain models + +**Fill-in instructions.** Describe every core object in your API. For each one: what it represents, its key fields and types, the states it can be in and how it moves between them, and which other objects it relates to. + +Ask: "Describe every core object in the API. For each: what it represents, its key fields and types, the states it can be in and how it moves between them, and which other objects it relates to." + +## Objects + +FICTIONAL EXAMPLE DATA. Replace these rows. + +### Order + +An order a customer places. Belongs to one `Customer`. Can have one `Invoice`. + +| Field | Type | Notes | +|---|---|---| +| `id` | string | Starts with `ord_` | +| `customer_id` | string | The customer who placed the order | +| `total` | integer | In cents | +| `status` | string | One of `draft`, `created`, `paid`, `canceled` | + +States: `draft` to `created` to `paid`. A `draft` or `created` order can move to `canceled`. A `paid` order cannot be canceled. + +### Customer + +A person or company that places orders. Fields: `id` (starts with `cus_`), `name`, `email`. + +### Invoice + +A bill for one order. Fields: `id` (starts with `inv_`), `order_id`, `due_date`, `status` (`open` or `paid`). diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/endpoints.md b/pipelines/docs-pipeline/_knowledge/product-kb/endpoints.md new file mode 100644 index 0000000..81af730 --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/endpoints.md @@ -0,0 +1,23 @@ +# Endpoints + +**Fill-in instructions.** List every API endpoint. For each one: the HTTP method and path, required and optional request parameters, the response object and its key fields, and any limits on which integration types can call it. + +Ask: "List every API endpoint. For each: the HTTP method and path, required and optional request parameters, the response object and key fields, and any restrictions on which integration types can call it." + +## Endpoint list + +FICTIONAL EXAMPLE DATA. Replace these rows. + +| Method and path | Required parameters | Optional parameters | Returns | Integration types | +|---|---|---|---|---| +| `POST /v1/orders` | `customer_id`, `total` | `currency`, `notes` | `Order` object | Server API, Hosted order form | +| `GET /v1/orders/{order_id}` | `order_id` | none | `Order` object | Server API | +| `POST /v1/orders/{order_id}/cancel` | `order_id` | `reason` | `Order` object with `status` set to `canceled` | Server API | +| `POST /v1/invoices` | `order_id` | `due_date` | `Invoice` object | Server API | + +## Limits + +FICTIONAL EXAMPLE DATA. + +- Rate limit: 100 requests per minute per API key. +- `total` is an integer in cents. diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/error-codes.md b/pipelines/docs-pipeline/_knowledge/product-kb/error-codes.md new file mode 100644 index 0000000..7834c01 --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/error-codes.md @@ -0,0 +1,15 @@ +# Error codes + +**Fill-in instructions.** List every error code or error type your API returns. For each one: the code, when it fires, what it means to a developer, and how your docs should describe it. + +Ask: "List every error code or error type the API returns. For each: the code, when it fires, what it means to a developer, and how our docs should describe it." + +## Codes + +FICTIONAL EXAMPLE DATA. Replace these rows. + +| Code | HTTP status | Fires when | How docs describe it | +|---|---|---|---| +| `invalid_order_id` | 404 | The `order_id` does not exist | "The provided `order_id` does not exist. Verify the value and try again." | +| `order_not_cancelable` | 409 | The order is already `paid` | "A paid order cannot be canceled. Create a credit note instead." | +| `rate_limited` | 429 | More than 100 requests in a minute | "Too many requests. Wait and retry." | diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/index.md b/pipelines/docs-pipeline/_knowledge/product-kb/index.md new file mode 100644 index 0000000..6792d03 --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/index.md @@ -0,0 +1,32 @@ +--- +extracted: 2026-10-01 +product: Acme Orders API (FICTIONAL EXAMPLE DATA, replace with your own product) +--- + +# Product knowledge base: index + +This folder is the source of truth that `/docs-sme-review` (Stage 4c) checks drafts against. The skill reads this file first, then the files it links to. + +**This copy is a starter.** The product here, the "Acme Orders API" with orders, customers and invoices, is made up. It exists so the pipeline runs end to end on the sample doc. Replace every example row with facts about your own product before you run Stage 4c on real docs. + +## How to fill this in + +1. Replace the `product:` line above with your product's name. +2. Fill in each file listed below. Delete the fictional example rows as you go. +3. Set `extracted:` above to today's date (`YYYY-MM-DD`). Do this again every time you change any file in this folder. +4. Stage 4c prints a staleness warning in every report when `extracted:` is more than 90 days old. + +## Files + +| File | What goes in it | +|---|---| +| [integration-types.md](./integration-types.md) | Each integration type or product tier, and what it can and cannot do | +| [endpoints.md](./endpoints.md) | Each API endpoint: path, parameters, response, who can call it | +| [domain-models.md](./domain-models.md) | Each core object: key fields, states, relationships | +| [error-codes.md](./error-codes.md) | Each error code: meaning, when it fires, how docs should describe it | +| [webhooks.md](./webhooks.md) | Each webhook event: when it fires, payload, who receives it | +| [recent-changes.md](./recent-changes.md) | API or product changes from the last 90 days that could make existing docs wrong | + +## Refresh instructions + +Ask your engineers, or your own API spec, the question listed at the top of each file. Paste the answers in as tables. Keep each file short enough to read in one pass: this folder is loaded into the model's context on every Stage 4c run. diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/integration-types.md b/pipelines/docs-pipeline/_knowledge/product-kb/integration-types.md new file mode 100644 index 0000000..89abc0d --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/integration-types.md @@ -0,0 +1,18 @@ +# Integration types + +**Fill-in instructions.** List every integration type or product tier you offer. For each one: what it is, which API resources it can use, which features are built in and which are manual, and what a developer using it can and cannot do. Stage 4c uses this table to catch docs that tell a reader they can do something their integration type does not allow. + +Ask: "Describe every integration type or product tier we offer. For each: what it is, what API resources are available, what features are built in vs. manual, and what a developer using it can and cannot do." + +## Capability matrix + +FICTIONAL EXAMPLE DATA. Replace these rows. + +| Integration type | Resources it can use | Built in | Not available | +|---|---|---|---| +| Server API | `orders`, `customers`, `invoices` | Order status updates, invoice numbering | Browser-side order forms | +| Hosted order form | `orders`, `customers` | Address validation, order confirmation page | Direct access to `invoices` | + +## Notes + +- Add anything a writer would need to avoid confusing one integration type with another. diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/recent-changes.md b/pipelines/docs-pipeline/_knowledge/product-kb/recent-changes.md new file mode 100644 index 0000000..b653dbc --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/recent-changes.md @@ -0,0 +1,14 @@ +# Recent changes + +**Fill-in instructions.** List every API or product change from the last 90 days that could make existing documentation wrong: deprecated fields, renamed resources, new required parameters, changed behavior. This file is a rolling window. Delete entries older than 90 days. + +Ask: "What has changed in the API or product in the last 90 days? List anything that might make existing documentation inaccurate: deprecated fields, renamed resources, new required parameters, changed behavior." + +## Changes + +FICTIONAL EXAMPLE DATA. Replace these rows. + +| Date | Change | Docs that may be wrong | +|---|---|---| +| 2026-09-15 | `POST /v1/orders` now requires `customer_id` | Any quickstart that creates an order without a customer | +| 2026-09-01 | `note` field renamed to `notes` | Any request example that sends `note` | diff --git a/pipelines/docs-pipeline/_knowledge/product-kb/webhooks.md b/pipelines/docs-pipeline/_knowledge/product-kb/webhooks.md new file mode 100644 index 0000000..3eeba8b --- /dev/null +++ b/pipelines/docs-pipeline/_knowledge/product-kb/webhooks.md @@ -0,0 +1,17 @@ +# Webhooks + +**Fill-in instructions.** List every webhook event. For each one: the event name, when it fires, the payload structure, and which integration types or product tiers receive it. + +Ask: "List every webhook event. For each: the event name, when it fires, the payload structure, and which integration types or product tiers receive it." + +## Events + +FICTIONAL EXAMPLE DATA. Replace these rows. + +| Event | Fires when | Payload | Sent to | +|---|---|---|---| +| `order.created` | An order moves from `draft` to `created` | `Order` object | Server API | +| `order.canceled` | An order moves to `canceled` | `Order` object | Server API | +| `invoice.paid` | An invoice moves to `paid` | `Invoice` object | Server API | + +Hosted order form integrations do not receive webhooks. diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/api-reference/style-guide_api-reference.md b/pipelines/docs-pipeline/_knowledge/style-guides/api-reference/style-guide_api-reference.md index 3253a0e..20ad0bc 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/api-reference/style-guide_api-reference.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/api-reference/style-guide_api-reference.md @@ -5,8 +5,8 @@ - Use sentence case for descriptions - Use backticks for inline code: field names, parameters, schema keys - Pluralize code terms by placing “s” outside backticks unless plural exists in API - - `PaymentMethod`s - - not `PaymentMethods` + - `Invoice`s + - not `Invoices` - Use fenced code blocks with language hints (`json`, `bash`) - Use tables for parameters and schemas - Use bullet lists for constraints or options @@ -23,14 +23,14 @@ | Authentication token | `Authentication token` | | Redirect URL | `Redirect URL` | | Customer ID | `customer_id` | -| Merchant ID | `merchant_id` | +| Order ID | `order_id` | - Examples: | Usage | Example | | ----- | ------------------------------------------------------------- | -| Do | Use the `merchant_id` field to identify the merchant account. | -| Don’t | Use the merchant ID to identify the merchant account. | +| Do | Use the `order_id` field to identify the order. | +| Don’t | Use the order ID to identify the order. | ## Error Message Structure @@ -41,9 +41,9 @@ | Usage | Example | | ----- | -------------------------------------------------------------------------------------------------- | -| Do | `Invalid merchant_id` — The provided `merchant_id` does not exist. Verify the value and try again. | +| Do | `Invalid order_id` — The provided `order_id` does not exist. Verify the value and try again. | | Do | `Expired session` — The session has expired. Create a new session and retry the request. | -| Don’t | Invalid merchant ID — This merchant ID is wrong. | +| Don’t | Invalid order ID — This order ID is wrong. | | Don’t | Session expired. Please try again. | ## Example Ordering and Content @@ -87,9 +87,9 @@ | Usage | Example | | ----- | --------------------------------------------------------------- | -| Do | A POST request to `/transactions` creates a new transaction. | +| Do | A POST request to `/orders` creates a new order. | | Do | Tokens expire after 24 hours. Refresh them before they do. | -| Don’t | Let's now go ahead and try issuing a refund! | +| Don’t | Let's now go ahead and try creating an order! | | Don’t | Developers may want to consider refreshing tokens occasionally. | ## Avoid Marketing or Sales Language @@ -99,9 +99,9 @@ | Usage | Example | | ----- | ------------------------------------------------------------------ | -| Do | You can use this endpoint to check a card's balance. | -| Do | This endpoint returns the transaction ID for a successful request. | -| Don’t | Our powerful API makes payments a breeze! | +| Do | You can use this endpoint to check an order's status. | +| Do | This endpoint returns the order ID for a successful request. | +| Don’t | Our powerful API makes ordering a breeze! | | Don’t | Unlock the full potential of your integration. | ## Reader Assumptions @@ -139,22 +139,22 @@ Example: | Usage | Example | | ----- | --------------------------------------------------------------------------------------------------------------------- | -| Do | Retrieves the status of a transaction by its `transaction_id`. Requires merchant authentication. | -| Don’t | This endpoint will let you check the transaction status when you have the transaction ID and merchant authentication. | +| Do | Retrieves the status of an order by its `order_id`. Requires API authentication. | +| Don’t | This endpoint will let you check the order status when you have the order ID and API authentication. | ### Parameter Description | Usage | Example | | ----- | ------------------------------------------ | -| Do | The `amount` of the transaction, in cents. | -| Don’t | Amount for the transaction. | +| Do | The `total` of the order, in cents. | +| Don’t | Total for the order. | ### Error Message | Usage | Example | | ----- | -------------------------------------------------------------------------------------------------- | -| Do | `Invalid merchant_id` — The provided `merchant_id` does not exist. Verify the value and try again. | -| Don’t | Invalid merchant ID — This merchant ID is wrong. | +| Do | `Invalid order_id` — The provided `order_id` does not exist. Verify the value and try again. | +| Don’t | Invalid order ID — This order ID is wrong. | ### Terminology Consistency diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/README.md b/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/README.md index 85f3358..83d9b15 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/README.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/README.md @@ -1,6 +1,6 @@ # Diagram Style Guide -Rules for when and how to use diagrams in The Product documentation. Covers diagram type selection, Mermaid conventions, color palette, complexity limits, and context requirements. +Rules for when and how to use diagrams in Acme Orders documentation. Covers diagram type selection, Mermaid conventions, color palette, complexity limits, and context requirements. ## Style Guides diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/style-guide_diagrams.md b/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/style-guide_diagrams.md index 1da9552..76cf66e 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/style-guide_diagrams.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diagrams/style-guide_diagrams.md @@ -1,6 +1,6 @@ # Diagram Style Guide -Rules for when and how to use diagrams in The Product documentation. Mermaid is the default rendering engine. All diagrams are written inline in markdown code blocks. +Rules for when and how to use diagrams in Acme Orders documentation. Mermaid is the default rendering engine. All diagrams are written inline in markdown code blocks. ## When to use a diagram @@ -8,7 +8,7 @@ A diagram earns its place when it communicates something that prose alone strugg **Strong candidates (use a diagram):** - Three or more parties exchanging messages across steps, especially with async handoffs, redirects, or timing constraints -- Branching decisions where a wrong path has real consequences (wrong API call, settlement error, item decline) +- Branching decisions where a wrong path has real consequences (wrong API call, fulfillment error, rejected order) - A process with named states that transition based on conditions or events - Timing constraints or ordering dependencies that are easy to miss in prose @@ -23,9 +23,9 @@ A diagram earns its place when it communicates something that prose alone strugg | Content pattern | Mermaid type | When to use | |---|---|---| -| Multiple parties exchanging messages | `sequenceDiagram` | API call flows, payment capture sequences, webhook delivery chains | +| Multiple parties exchanging messages | `sequenceDiagram` | API call flows, order creation sequences, webhook delivery chains | | Branching decisions with outcomes | `flowchart TD` | Decision trees, validation flows, error handling paths | -| Named states with transitions | `stateDiagram-v2` | Payment lifecycles, order status flows, onboarding stages | +| Named states with transitions | `stateDiagram-v2` | Invoice lifecycles, order status flows, onboarding stages | | Math, allocation, or comparison | Annotated table (not Mermaid) | Proration calculations, discount allocation, feature comparison | When in doubt between a flowchart and a sequence diagram: if the emphasis is on who does what, use a sequence diagram. If the emphasis is on what happens next, use a flowchart. @@ -57,18 +57,18 @@ Use `rect` blocks with `rgb()` background colors to separate logical phases. Thi ```mermaid sequenceDiagram participant App as Your App - participant The Product + participant API as Acme Orders rect rgb(219, 234, 254) - Note over App, The Product: Phase 1 — Setup - App->>The Product: Create session - The Product-->>App: Session token + Note over App, API: Phase 1 — Setup + App->>API: Create session + API-->>App: Session token end rect rgb(209, 250, 229) - Note over App, The Product: Phase 2 — Payment - App->>The Product: Capture payment - The Product-->>App: Payment result + Note over App, API: Phase 2 — Order + App->>API: Create order + API-->>App: Order result end ``` @@ -76,7 +76,7 @@ Participant aliases: use short, readable names. `App as Your App` not `App as Yo Failure notation: use `--x` (dashed with X) for explicit connection breaks or failures. Add a `Note` explaining what failed and why. -Timing constraints: use `Note over` to call out expiration windows, validity periods, or ordering dependencies (e.g., "Session ref valid until pin_expires_at"). +Timing constraints: use `Note over` to call out expiration windows, validity periods, or ordering dependencies (e.g., "Session token valid until expires_at"). ### State diagrams @@ -105,7 +105,7 @@ Use these semantic color classes consistently within a guide set. Not every diag |---|---|---|---| | Setup / configuration | `#dbeafe` | `#2563eb` | setup | | Session / context | `#e0e7ff` | `#4f46e5` | session | -| Payment / success | `#d1fae5` | `#059669` | payment | +| Order / success | `#d1fae5` | `#059669` | order | | Decision / branch | `#fef3c7` | `#d97706` | decision | | Neutral / delivery | `#f3f4f6` | `#6b7280` | delivery | | Warning / error | `#fee2e2` | `#dc2626` | warning | @@ -115,17 +115,17 @@ Apply with `classDef` and `class` in flowcharts: ```mermaid flowchart TD A[Create session] --> B{Valid?} - B -->|Yes| C[Process payment] + B -->|Yes| C[Process order] B -->|No| D[Return error] classDef setup fill:#dbeafe,stroke:#2563eb classDef decision fill:#fef3c7,stroke:#d97706 - classDef payment fill:#d1fae5,stroke:#059669 + classDef order fill:#d1fae5,stroke:#059669 classDef warning fill:#fee2e2,stroke:#dc2626 class A setup class B decision - class C payment + class C order class D warning ``` @@ -142,9 +142,9 @@ Every diagram needs prose around it. A diagram without context is a puzzle. One to two sentences explaining what the reader is about to see and why it matters. Frame it as "here's the thing you need to understand" not "the following diagram shows." ```markdown -The payment capture flow involves three parties. Your app creates a session, -the customer enters their PIN in the browser, and The Product authorizes the -payment with the benefits-card network. +The order creation flow involves three parties. Your app creates a session, +the customer confirms the order in the browser, and Acme Orders validates the +order with the invoicing service. ``` ### Title @@ -170,14 +170,14 @@ A diagram that requires horizontal scrolling on a standard viewport has failed. For math, proration, or allocation scenarios, use a worked-example table with column headers for each category and rows for each line item. Include a totals row. Add a brief annotation below explaining the formula or logic. ```markdown -| Item | AcmePay eligible | Amount | AcmePay covers | Customer pays | +| Item | Discount eligible | Amount | Discount applied | Customer pays | |---|---|---|---|---| -| Milk (1 gal) | Yes | $4.50 | $4.50 | $0.00 | -| Chips | No | $3.99 | $0.00 | $3.99 | -| **Total** | | **$8.49** | **$4.50** | **$3.99** | +| Notebook | Yes | $4.50 | $0.50 | $4.00 | +| Pen set | No | $3.99 | $0.00 | $3.99 | +| **Total** | | **$8.49** | **$0.50** | **$7.99** | -AcmePay benefits apply to eligible items first. The remaining balance is charged -to the customer's selected payment method. +Discounts apply to eligible items first. The remaining balance is added to the +customer's invoice. ``` ## Process artifacts diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/README.md b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/README.md index 6556f8e..27e7edd 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/README.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/README.md @@ -30,7 +30,7 @@ Maintain strict separation between types. Common violations: - **Reference → Explanation**: Explaining design decisions or reasoning - **Explanation → How-to**: Prescribing specific actions -## The Product Guide Sets +## Acme Orders Guide Sets Every multi-doc guide includes a **guide set overview** (not a Diataxis type) as the entry point, plus the relevant typed docs: diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_explanation.md b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_explanation.md index f804c7a..6cf9ddc 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_explanation.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_explanation.md @@ -22,7 +22,7 @@ Clarify concepts and provide understanding. Answer "why" and "how it works," not Required patterns: "Understanding [concept]", "How [system] works", "[Concept] explained", "About [topic]", or direct concept name. -✅ "Understanding benefits-card transaction flow", "How eligibility-program eligibility works", "Authentication models explained" +✅ "Understanding the order lifecycle", "How invoice matching works", "Authentication models explained" ❌ "How to implement webhooks" (How-to), "Create your first webhook" (Tutorial) ### Opening Section (Required) @@ -63,9 +63,9 @@ Exclude: repetitive summaries, calls to action, instructions. ✅ Right (explanatory): "Webhook handling requires an endpoint and signature verification. The signature mechanism prevents attackers from sending fake events." -❌ Wrong (reference): "POST /v1/payments | Parameters: amount (number, required)..." +❌ Wrong (reference): "POST /v1/orders | Parameters: total (number, required)..." -✅ Right (explanatory): "Payment amounts are specified in smallest currency units (cents for USD) to avoid floating-point precision issues that could accumulate across transactions." +✅ Right (explanatory): "Order totals are specified in smallest currency units (cents for USD) to avoid floating-point precision issues that could accumulate across invoices." ## Writing Style Rules @@ -93,10 +93,10 @@ Exclude: repetitive summaries, calls to action, instructions. "Idempotency keys are like package tracking numbers. They always refer to the same operation regardless of how many times submitted." **Contrasts:** -"Unlike credit cards with separate auth/capture, benefits-program transactions are always real-time because benefits are actual funds, not credit." +"Unlike invoices that are paid after delivery, prepaid orders are always confirmed in real time because the payment has already cleared." **Causation chains:** -"USDA requires PIN → mandates online processing → needs connectivity → affects offline-first architecture" +"Tax rules require a signed total → mandates online validation → needs connectivity → affects offline-first architecture" ## Visual Elements @@ -118,7 +118,7 @@ def verify_signature(payload, signature, secret): ### Tables (For Comparisons) -Use to contrast payment methods, authorization models, refund windows, etc. +Use to contrast order types, payment terms, cancellation windows, etc. ## Common Mistakes @@ -128,23 +128,23 @@ Use to contrast payment methods, authorization models, refund windows, etc. 4. **Too Surface**: Doesn't deepen understanding → Fix: Go deeper into "why" and "how it works" 5. **Assumes Too Much**: Unexplained jargon → Fix: Define terms, build understanding progressively -## benefits-card/Compliance Context +## Domain and Compliance Context -### eligibility-program Regulations +### Tax and Shipping Rules -When explaining benefits-program requirements: +When explaining tax or shipping requirements: -- State regulatory mandates clearly (USDA, state rules) -- Explain why requirements exist (fraud prevention, recipient protection, taxpayer accountability) -- Connect regulations to technical implications (PIN → online processing → connectivity requirements) +- State regulatory mandates clearly (tax authority and regional rules) +- Explain why requirements exist (fraud prevention, customer protection, audit accountability) +- Connect regulations to technical implications (signed total → online validation → connectivity requirements) -### Eligible Item Verification +### Taxable Item Verification -Explain complexity of eligibility-program eligible item rules, variability across states, technical challenges in real-time verification. +Explain the complexity of taxable item rules, variability across regions, and technical challenges in real-time verification. -### Real-time Authorization +### Real-time Confirmation -Contrast with credit card auth/capture model. Explain why benefits-card requires immediate settlement. +Contrast with the invoice-after-delivery model. Explain why prepaid orders require immediate confirmation. ## Template diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_how-to-guides.md b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_how-to-guides.md index c1ae94a..13cfb30 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_how-to-guides.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_how-to-guides.md @@ -43,7 +43,7 @@ Integrate SAML 2.0 single sign-on for enterprise customers. ## Prerequisites -- Admin access to The Product dashboard +- Admin access to Acme Orders dashboard - SAML metadata from identity provider ## When to use this @@ -85,7 +85,7 @@ Include when common problems predictable, errors have specific solutions, or use ### Error: "Invalid SAML response" -**Cause**: Clock skew between IdP and The Product servers +**Cause**: Clock skew between IdP and Acme Orders servers **Solution**: Ensure NTP configured. Max clock skew: 60 seconds. ``` diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_reference.md b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_reference.md index afabb33..59b4d73 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_reference.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_diataxis-type_reference.md @@ -40,7 +40,7 @@ Avoid: "How to use...", "Understanding...", "Getting started..." ## Content Templates -**API Endpoint**: Title `## POST /v1/merchants` → Description (1 line) → **Request** (headers, body params table) → **Response** (success code + object, error codes) → **Example** (minimal curl/code) +**API Endpoint**: Title `## POST /v1/orders` → Description (1 line) → **Request** (headers, body params table) → **Response** (success code + object, error codes) → **Example** (minimal curl/code) **Function/Method**: Title `## calculateTotal()` → Description → **Syntax** (signature) → **Parameters** (table or inline: name, type, required, description+constraints+defaults) → **Returns** (type + description) → **Throws** (error types + conditions) → **Example** @@ -48,7 +48,7 @@ Avoid: "How to use...", "Understanding...", "Getting started..." **Error Code**: Title `## E_CODE_NAME` → Code | HTTP | Category → Description → Causes (list) → Resolution (list) → Related codes -**Object/Model**: Title `## Merchant Object` → Description → **Attributes** table (attribute, type, description+constraints) → **Example** (JSON) +**Object/Model**: Title `## Order Object` → Description → **Attributes** table (attribute, type, description+constraints) → **Example** (JSON) **Enumeration**: Title `## Status` → Table (value, description) → Type | Used in (inline) @@ -56,7 +56,7 @@ Avoid: "How to use...", "Understanding...", "Getting started..." **Voice**: Third person, neutral, present tense. Technical precision over readability. No imperative/opinions/recommendations. -- ✅ "Returns Merchant object" ❌ "This will return..." +- ✅ "Returns Order object" ❌ "This will return..." - ✅ "Throws TypeError if not array" ❌ "Make sure items is an array" **Requirements**: Exhaustive (ALL params/values/errors/constraints), Precise (exact types/constraints/defaults), Consistent (format/ordering/terminology) @@ -70,7 +70,7 @@ Avoid: "How to use...", "Understanding...", "Getting started..." **Exclude**: Instructions ("First, do X..."), explanations (why/how internally), advice ("We recommend..."), tutorials, problem-solving - ❌ "To authenticate, first obtain API key, then include in header" → ✅ "Authentication requires Bearer token in Authorization header" -- ❌ "We use idempotency keys to prevent duplicate charges" → ✅ "Idempotency-Key (string, optional): Prevents duplicates. Max 255 chars. 24hr cache" +- ❌ "We use idempotency keys to prevent duplicate orders" → ✅ "Idempotency-Key (string, optional): Prevents duplicates. Max 255 chars. 24hr cache" ## Formatting @@ -89,11 +89,11 @@ Avoid: "How to use...", "Understanding...", "Getting started..." ## Common Mistakes -- ❌ "To create a merchant, send POST..." → ✅ "POST /v1/merchants creates merchant" +- ❌ "To create an order, send POST..." → ✅ "POST /v1/orders creates order" - ❌ "Webhooks work by sending HTTP..." → ✅ "Webhook endpoints receive POST requests" - ❌ Document only "important" params → ✅ Document ALL params - ❌ "String. Keep it short." → ✅ "String. Max 255 chars. Pattern: ^[A-Za-z0-9_-]+$" -- ❌ "We recommend async/await" → ✅ "Returns Promise" +- ❌ "We recommend async/await" → ✅ "Returns Promise" ## Template diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md index d9efc9e..c32407f 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md @@ -4,7 +4,7 @@ The overview is the customer's entry point to a guide set. It explains what the ## What This Document Is -The overview document is not one of the four Diataxis content types. It is a The Product-specific entry point that sits above the guide set. Every multi-doc guide set must have one. +The overview document is not one of the four Diataxis content types. It is an Acme Orders-specific entry point that sits above the guide set. Every multi-doc guide set must have one. It can draw from any Diataxis type (a paragraph of explanation here, a conceptual diagram there, a brief prerequisite list) to help the reader understand the guide and orient themselves within it. There is no single prescribed form. The only hard rule is its function: it is the first thing a customer reads, and it explains all the Diataxis pieces that sit alongside it. @@ -42,13 +42,13 @@ docs/{Category}/ Required pattern: `[Product/Feature] [Guide Type]` -Good: "AcmePay Integration Guide", "HSA/FSA Payment Guide", "Backend-to-Backend Integration Guide" -Bad: "Introduction to AcmePay", "Getting Started with AcmePay", "AcmePay Overview" (too vague or instructional) +Good: "Acme Orders Integration Guide", "Prepaid Orders Guide", "Backend-to-Backend Integration Guide" +Bad: "Introduction to Acme Orders", "Getting Started with Acme Orders", "Acme Orders Overview" (too vague or instructional) ### Required Sections (always present, always in this order) 1. **Lead paragraph**. One to two sentences. What this guide covers at the highest level and why it exists. No section heading. -2. **## Audience**. Who this guide is written for. One to two sentences. Name the role (e.g. "payment engineers and product managers") and any assumed baseline (e.g. "who have integrated benefits-program with The Product"). +2. **## Audience**. Who this guide is written for. One to two sentences. Name the role (e.g. "integration engineers and product managers") and any assumed baseline (e.g. "who have already created an Acme Orders account"). 3. **## Prerequisites**. What the reader needs before starting. One to two sentences or a short bullet list. Be specific. 4. **## What's in this guide**. A bullet list of every document in the guide set. Each bullet: `**[Linked doc title]**. One sentence describing what that doc covers.` @@ -67,9 +67,9 @@ Each entry must: Example: ```markdown -- **[Understanding AcmePay Payments](./acmepay-payments.md)**. How AcmePay differs from dollar-based payment methods: the item-based voucher model, the payment lifecycle, and straddle rules. -- **[How to Integrate AcmePay with The Product](./acmepay-integration.md)**. Step-by-step instructions for each phase of the integration: syncing APL data, retrieving benefits, building the cart, capturing payment, and processing refunds. -- **[AcmePay API Reference](./acmepay-api-reference.md)**. Complete endpoint specifications, capture action codes, error codes, transaction limits, and receipt requirements. +- **[Understanding the Acme Orders Lifecycle](./acme-orders-lifecycle.md)**. How an order moves from draft to paid: the order lifecycle, invoice matching, and cancellation rules. +- **[How to Integrate Acme Orders](./acme-orders-integration.md)**. Step-by-step instructions for each phase of the integration: syncing customers, creating an order, generating an invoice, and canceling an order. +- **[Acme Orders API Reference](./acme-orders-api-reference.md)**. Complete endpoint specifications, status codes, error codes, rate limits, and invoice requirements. ``` ## Core Content Rules @@ -95,13 +95,13 @@ Example: - Direct and efficient. Every sentence earns its place. - No marketing language, no filler phrases -Good: "Your AcmePay integration builds on your existing benefits-program integration." -Bad: "Welcome to the AcmePay Integration Guide! We're excited to help you get started." +Good: "Your Acme Orders integration builds on your existing customer sync." +Bad: "Welcome to the Acme Orders Integration Guide! We're excited to help you get started." ### Language - One sentence per idea -- Prefer concrete over abstract: "payment engineers" not "technical users" +- Prefer concrete over abstract: "integration engineers" not "technical users" - Audience and Prerequisites sections can use bullets if there are multiple discrete items; otherwise prose ## Common Mistakes diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/general/README.md b/pipelines/docs-pipeline/_knowledge/style-guides/general/README.md index 9304790..7e0e248 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/general/README.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/general/README.md @@ -1,7 +1,7 @@ # General Style Guide -Voice, tone, formatting, and structural conventions for all The Product documentation (guides, quickstarts, implementation docs). +Voice, tone, formatting, and structural conventions for all Acme Orders documentation (guides, quickstarts, implementation docs). ## Style Guides -- **style-guide_general.md** - The Product-wide writing standards covering terminology, formatting, structure, and tone +- **style-guide_general.md** - Acme Orders-wide writing standards covering terminology, formatting, structure, and tone diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md b/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md index 18903d1..46d38a3 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/general/style-guide_general.md @@ -1,6 +1,6 @@ -# THE PRODUCT GENERAL STYLE GUIDE — MACHINE RULESET +# ACME ORDERS GENERAL STYLE GUIDE — MACHINE RULESET ## VOICE AND TONE @@ -17,8 +17,8 @@ | Usage | Example | | ---------------------- | ------------------------------------------- | -| Direct, confident tone | "You create a refund with `POST /refunds`." | -| Prohibited casual tone | "Let's go ahead and refund a transaction!" | +| Direct, confident tone | "You create an order with `POST /orders`." | +| Prohibited casual tone | "Let's go ahead and create an order!" | ## READER ASSUMPTIONS @@ -31,7 +31,7 @@ | Usage | Example | | ---------------------- | --------------------------------------------------------- | -| Introduce term | "The `transaction_type` field controls capture behavior." | +| Introduce term | "The `order_type` field controls fulfillment behavior." | | Out-of-the-box example | Copy, replace placeholders, run. | ## STRUCTURE @@ -45,7 +45,7 @@ | Usage | Example | | -------------- | ------------------------------------------------------- | | Concise title | `Configure webhooks` | -| Key idea first | "Use the `merchant_id` field to identify the merchant." | +| Key idea first | "Use the `customer_id` field to identify the customer." | ## LISTS @@ -58,7 +58,7 @@ - Numbered lists represent task sequences. - Numbered list steps must be written using imperative verbs. - The order of steps in numbered lists is mandatory. -- Every numbered (procedural) list MUST be introduced with bold text (wrapped in double asterisks) that begins with "To" and ends with a colon (e.g., "**To perform a balance check:**"). +- Every numbered (procedural) list MUST be introduced with bold text (wrapped in double asterisks) that begins with "To" and ends with a colon (e.g., "**To check an order's status:**"). - Headings or subheadings may appear above the "To" lead-in for navigation purposes, but the "To" lead-in is always required immediately before the numbered steps. - Every numbered (procedural) list MUST be followed immediately by a single, plain-language sentence that confirms successful completion of the steps and explains the expected outcome or resulting system state. - The outcome sentence MUST NOT start with "After completing these steps" or similar phrases, as completion is assumed. Use direct phrasing such as "This will…" or state the outcome directly. @@ -67,11 +67,11 @@ | Usage | Example | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bulleted list (conceptual) | "When a refund is processed:\n- The system validates the payment ID.\n- Funds are returned to the original payment method.\n- A confirmation email is sent to the customer." | +| Bulleted list (conceptual) | "When an order is canceled:\n- The system validates the order ID.\n- Reserved stock is released.\n- A confirmation email is sent to the customer." | | Numbered list (procedural) | "**To configure API authentication:**\n\n1. Navigate to the API settings page.\n2. Generate a new API key.\n3. Copy the key to your environment variables.\n\nYour application will authenticate using the new key." | | Numbered list with heading | "### Configure API authentication\n\n**To configure API authentication:**\n\n1. Navigate to the API settings page.\n2. Generate a new API key.\n3. Copy the key to your environment variables.\n\nYour application will authenticate using the new key." | | Required outcome sentence | "This will configure webhook delivery to your endpoint." | -| Outcome sentence (avoid) | "After completing these steps, the payment is processed." | +| Outcome sentence (avoid) | "After completing these steps, the order is created." | ## TABLES @@ -110,8 +110,8 @@ Not this: | Usage | Example | | ----------------- | ------------------------ | -| Exact field | Use `transaction_type` | -| Consistent naming | Always use `merchant_id` | +| Exact field | Use `order_type` | +| Consistent naming | Always use `customer_id` | ## CODE SAMPLES @@ -124,8 +124,8 @@ Not this: | Usage | Example | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Request | `bash\ncurl -X POST https://api.example.com/v1/refunds \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -d '{\"payment_id\":\"pay_123\",\"amount\":500}'\n` | -| Response | `json\n{\"id\":\"ref_123\",\"status\":\"succeeded\"}\n` | +| Request | `bash\ncurl -X POST https://api.example.com/v1/orders \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -d '{\"customer_id\":\"cus_123\",\"total\":500}'\n` | +| Response | `json\n{\"id\":\"ord_123\",\"status\":\"created\"}\n` | | Placeholder value | `your_client_id` | ## CALLOUTS @@ -182,7 +182,7 @@ Not this: - Use "you" to address the developer in sentences and paragraphs. - Use imperative form (without "you") in list items for brevity. - Use imperative form (without "you") in headings, subheadings, and bold section labels. -- Use "customers" (not "your customers") when referring to the developer/merchant's customers. The context makes it clear whose customers are being discussed. +- Use "customers" (not "your customers") when referring to the developer's customers. The context makes it clear whose customers are being discussed. - Use active voice. - Avoid passive voice. - Do not use "we" unless the system is acting. @@ -192,12 +192,12 @@ Not this: | Usage | Example | | -------------------------- | ----------------------------------------------------------------------------- | | Active instruction | "You update the key every 90 days." | -| Heading/subheading | "Pass the Stripe Customer ID to subsequent sessions." | -| Heading/subheading (avoid) | "You pass the Stripe Customer ID to subsequent sessions." | +| Heading/subheading | "Pass the customer ID to subsequent requests." | +| Heading/subheading (avoid) | "You pass the customer ID to subsequent requests." | | List item (imperative) | "Pass the `customer_id` field in the request body." | | List item (imperative) | "Store the `ref` in your database." | -| Customer reference | "Custom Checkout allows customers to reuse their saved payment methods." | -| Customer reference (avoid) | "Custom Checkout allows your customers to reuse their saved payment methods." | +| Customer reference | "Acme Orders allows customers to reuse their saved shipping addresses." | +| Customer reference (avoid) | "Acme Orders allows your customers to reuse their saved shipping addresses." | | System subject | "We return a 200 OK on success." | ## CROSS-REFERENCING @@ -210,8 +210,8 @@ Not this: | Usage | Example | | --------------- | -------------------------------- | -| Inline link | "See the `Refund` object." | -| RELATED callout | `RELATED: Refund API reference.` | +| Inline link | "See the `Order` object." | +| RELATED callout | `RELATED: Order API reference.` | ## VISUALS @@ -223,9 +223,9 @@ Not this: | Usage | Example | | ------------------- | ---------------------------------------------------------------------- | -| Image placeholder | `> 🔴 **IMAGE PLACEHOLDER**\n> image showing save card option for benefits-card` | -| Image placeholder | `> 🔴 **IMAGE PLACEHOLDER**\n> saved benefits-card card displayed in checkout` | -| Diagram placeholder | `[Placeholder: settlement flow for refunds]` | +| Image placeholder | `> 🔴 **IMAGE PLACEHOLDER**\n> image showing the save address option on the order form` | +| Image placeholder | `> 🔴 **IMAGE PLACEHOLDER**\n> saved address displayed on the order form` | +| Diagram placeholder | `[Placeholder: fulfillment flow for orders]` | ## INFORMATION ARCHITECTURE @@ -238,7 +238,7 @@ Not this: | Usage | Example | | -------------- | ---------------------------------- | -| Workflow group | `Integration > Payments > Refunds` | +| Workflow group | `Integration > Orders > Cancellations` | | Topic grouping | `Authentication > API Keys` | ## GENERAL PRINCIPLES @@ -252,7 +252,7 @@ Not this: | Usage | Example | | ----------------- | --------------------------------- | -| Useful heading | "Create sandbox merchant account" | +| Useful heading | "Create a sandbox account" | | Prohibited filler | "In this guide, we will discuss…" | ## DO AND DON'T @@ -264,8 +264,8 @@ Not this: | Usage | Example | | ----- | ------------------------------------------ | -| DO | "You can issue a refund using `/refunds`." | -| DON'T | "Insert the ID for the payout." | +| DO | "You can cancel an order using `/orders`." | +| DON'T | "Insert the ID for the shipment." | ## END EVERY DOC WITH A PROMPT FOR THE READER'S AI MODEL @@ -328,7 +328,7 @@ Paste this into any AI model, together with this document and the files it descr All rules for identifying and removing AI-generated writing patterns (em dashes, banned words, filler phrases, sentence structure) live in the **Write Like a Human** style guide: -`_extras/style-guides/write-like-a-human/style-guide_write-like-a-human.md` +`_knowledge/style-guides/write-like-a-human/style-guide_write-like-a-human.md` Apply that guide as a final editing pass on all documentation before publication. diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/illustrations/README.md b/pipelines/docs-pipeline/_knowledge/style-guides/illustrations/README.md index e91a698..f518b04 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/illustrations/README.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/illustrations/README.md @@ -1,6 +1,6 @@ # Illustration Style Guide -Rules for when and how to use illustrations in The Product documentation. Content TBD. +Rules for when and how to use illustrations in Acme Orders documentation. Content TBD. ## Style Guides diff --git a/pipelines/docs-pipeline/_knowledge/style-guides/images/README.md b/pipelines/docs-pipeline/_knowledge/style-guides/images/README.md index b1addfa..a6c8e80 100644 --- a/pipelines/docs-pipeline/_knowledge/style-guides/images/README.md +++ b/pipelines/docs-pipeline/_knowledge/style-guides/images/README.md @@ -1,6 +1,6 @@ # Image Style Guide -Rules for when and how to use images in The Product documentation. Content TBD. +Rules for when and how to use images in Acme Orders documentation. Content TBD. ## Style Guides diff --git a/pipelines/docs-pipeline/docs-diataxis-audit.md b/pipelines/docs-pipeline/docs-diataxis-audit.md index 7413073..a6d5cd0 100644 --- a/pipelines/docs-pipeline/docs-diataxis-audit.md +++ b/pipelines/docs-pipeline/docs-diataxis-audit.md @@ -18,6 +18,8 @@ This should be the path to the markdown file to audit. `/docs-diataxis-audit [file-path]` +**Optional shared folder:** `{SHARED_CONFIG_DIR}` may point at a folder of your own shared tools. If it is empty or still reads `{SHARED_CONFIG_DIR}`, treat it as unset and skip every step that needs it. + **Required:** The `[file-path]` parameter is mandatory. If not provided, stop and ask for the source document to audit. ## Steps @@ -27,13 +29,13 @@ This should be the path to the markdown file to audit. - Check that `[file-path]` is provided in $ARGUMENTS - If not provided, stop: "Please provide the file path to audit: `/docs-diataxis-audit [file-path]`" - Determine `INPUT_BASENAME` for output naming: - - **If running inside a workspace** (directory name starts with `workspace-`): Extract the guide name slug from the workspace folder name. The slug is everything after the ticket number portion. Example: `workspace-doc-1318-intro-to-billing` → `INPUT_BASENAME = "intro-to-billing"` + - **If running inside a workspace** (directory name starts with `workspace_`): Extract the guide name slug from the workspace folder name. The slug is everything after the ticket number portion. Example: `workspace_doc-1318_intro-to-billing` → `INPUT_BASENAME = "intro-to-billing"` - **Otherwise**: Get filename from `basename [file-path]`, remove extension (`.md`, `.markdown`). Example: `docs/source/guide.md` → `INPUT_BASENAME = "guide"` - All output files (audit report, mapping JSON, SVGs) are prefixed with `{INPUT_BASENAME}_`. This ensures every artifact is traceable to its guide, even when moved or referenced outside the workspace. 2. **Read the framework** - - Read and understand: `~/projects/example-docs-repo/_extras/style-guides/diataxis/README.md` + - Read and understand: `./_knowledge/style-guides/diataxis/README.md` - Focus on: four types, classification axes, boundary rules - Use `Read` tool - Note: Multiple files can be read in parallel if needed @@ -204,7 +206,7 @@ This should be the path to the markdown file to audit. | `00-overview.svg`, `01-*.svg`, ... | Visual mapping diagrams — overview shows all source → target flows; per-target-doc pages show the full source with relevant sections highlighted | ``` - Do not mention AI or automation tools. "The Product documentation team's structured conversion process" is the right framing. + Do not mention AI or automation tools. "Acme Orders documentation team's structured conversion process" is the right framing. Fill in `[N] sections` and `[N] output documents` with the actual numbers from your analysis before writing the file. @@ -263,12 +265,11 @@ This should be the path to the markdown file to audit. 12. **Generate and write JSON mapping** - Create JSON mapping following schema: `_shared/schemas/diataxis-audit-mapping/schema.json` + Create JSON mapping following the structure described in this step. If the optional schema `{SHARED_CONFIG_DIR}/schemas/diataxis-audit-mapping/schema.json` exists, follow it too. If `{SHARED_CONFIG_DIR}` is not set, use only the structure described here. a. **Read schema files** - - Read: `_shared/schemas/diataxis-audit-mapping/schema.json` - - Read: `_shared/schemas/diataxis-audit-mapping/README.md` - - Use `Read` tool (can read both in parallel) + - Only if `{SHARED_CONFIG_DIR}` is set and `{SHARED_CONFIG_DIR}/schemas/diataxis-audit-mapping/schema.json` exists: read it, and read `README.md` in the same folder if present. Use the `Read` tool. + - Otherwise skip this sub-step and use the structure and validation rules written out in sub-steps b to d below. Print: "Optional schema not found, using the built-in structure." - Understand structure, validation rules, dual-ID system b. **Generate section IDs** @@ -313,7 +314,8 @@ This should be the path to the markdown file to audit. 13. **Generate SVG visualizations** - - Command: `node _shared/tools/diataxis-mapper/generate-svg.js --multi --prefix {INPUT_BASENAME} docs/output/_process/diataxis-audit/{INPUT_BASENAME}_mapping.json docs/output/_process/diataxis-audit/` + - This step is optional. Only run it if `{SHARED_CONFIG_DIR}` is set and `{SHARED_CONFIG_DIR}/tools/diataxis-mapper/generate-svg.js` exists and `node` is installed. Otherwise skip it and print: "SVG step skipped: optional diagram tool not installed." + - Command: `node {SHARED_CONFIG_DIR}/tools/diataxis-mapper/generate-svg.js --multi --prefix {INPUT_BASENAME} docs/output/_process/diataxis-audit/{INPUT_BASENAME}_mapping.json docs/output/_process/diataxis-audit/` - Use `Bash` tool to execute the command - Output files (all prefixed with `{INPUT_BASENAME}_`): - `{INPUT_BASENAME}_00-overview.svg` — Complete overview showing all source → target mappings @@ -526,7 +528,7 @@ Handle these error conditions gracefully: ## Diataxis Framework Reference -**Full framework**: `~/projects/example-docs-repo/_extras/style-guides/diataxis/README.md` +**Full framework**: `./_knowledge/style-guides/diataxis/README.md` ### Quick Reference @@ -553,14 +555,12 @@ Handle these error conditions gracefully: **For complete details** (type definitions, classification decision tree, content patterns, anti-patterns, language requirements, content migration rules): -Read: `~/projects/example-docs-repo/_extras/style-guides/diataxis/README.md` +Read: `./_knowledge/style-guides/diataxis/README.md` ## Reference -- Framework source: `~/projects/example-docs-repo/_extras/style-guides/diataxis/README.md` -- Schema directory: `_shared/schemas/diataxis-audit-mapping/` - - JSON schema: `_shared/schemas/diataxis-audit-mapping/schema.json` - - Schema documentation: `_shared/schemas/diataxis-audit-mapping/README.md` +- Framework source: `./_knowledge/style-guides/diataxis/README.md` +- Optional schema directory (only if `{SHARED_CONFIG_DIR}` is set): `{SHARED_CONFIG_DIR}/schemas/diataxis-audit-mapping/` ## Sources diff --git a/pipelines/docs-pipeline/docs-diataxis-create-overview.md b/pipelines/docs-pipeline/docs-diataxis-create-overview.md index 188d3b4..c4aae20 100644 --- a/pipelines/docs-pipeline/docs-diataxis-create-overview.md +++ b/pipelines/docs-pipeline/docs-diataxis-create-overview.md @@ -22,7 +22,7 @@ The user provided: $ARGUMENTS ## Constants ``` -REFERENCE_DOC=~/projects/example-docs-repo/docs/AcmePay/acmepay-guide/index.md +REFERENCE_DOC=./_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md ``` --- @@ -84,8 +84,8 @@ If found, read it and extract: If no source doc exists, synthesize these from the output docs: - **Guide title**: Humanize the area prefix (e.g., `webhooks` → "Webhooks", `configure-webhooks` → "Configure Webhooks") - **Opening paragraph**: Synthesize from the typed docs' titles and purposes: `"This guide covers everything you need to [action implied by how-to title] using the product API."` -- **Audience**: `"Payment engineers and payment product managers integrating with the product API."` -- **Prerequisites**: `"An active The Product integration. If you haven't set that up yet, start with [getting started with The Product](https://docs.example-docs.app/docs/get-started)."` +- **Audience**: `"Integration engineers and product managers integrating with the Acme Orders API."` +- **Prerequisites**: `"An active Acme Orders integration. If you haven't set that up yet, start with [getting started with Acme Orders](https://docs.example.com/docs/get-started)."` --- @@ -109,7 +109,7 @@ The one-sentence description names the reader's purpose, not just the doc type: ### 5. Write the overview doc -**Filename:** `{GUIDE_PREFIX}_overview.md` during drafting (in the workspace), where `GUIDE_PREFIX` is the guide name slug from the workspace folder name (e.g., `intro-to-billing` from `workspace-doc-1318-intro-to-billing`). At publish time, `/docs-publish` renames this to `index.md` in the guide's subdirectory. +**Filename:** `{GUIDE_PREFIX}_overview.md` during drafting (in the workspace), where `GUIDE_PREFIX` is the guide name slug from the workspace folder name (e.g., `intro-to-billing` from `workspace_doc-1318_intro-to-billing`). At publish time, `/docs-publish` renames this to `index.md` in the guide's subdirectory. If no workspace context exists (standalone run), fall back to `index.md`. @@ -191,7 +191,7 @@ Created: {DOCS_DIR}/index.md ## Reference -The overview doc follows the same pattern as `acmepay-overview.md` in `example-docs-repo`. Key characteristics: +The overview doc follows the rules in `REFERENCE_DOC` (`_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md`). Key characteristics: - Short (15–25 body lines). Its job is to route, not inform. - Opening paragraph orients the reader to the product capability, not to the docs themselves. diff --git a/pipelines/docs-pipeline/docs-diataxis-split.md b/pipelines/docs-pipeline/docs-diataxis-split.md index b431e62..2910048 100644 --- a/pipelines/docs-pipeline/docs-diataxis-split.md +++ b/pipelines/docs-pipeline/docs-diataxis-split.md @@ -84,7 +84,7 @@ For each entry in `original_document.sections[]`: #### 4a. Determine all filenames first -**Guide name prefix:** If running inside a workspace (directory name starts with `workspace-`), extract the guide name slug from the workspace folder name. The slug is everything after the ticket number portion. Example: `workspace-doc-1318-intro-to-billing` → `GUIDE_PREFIX = "intro-to-billing"`. All output files are prefixed with `{GUIDE_PREFIX}_`. +**Guide name prefix:** If running inside a workspace (directory name starts with `workspace_`), extract the guide name slug from the workspace folder name. The slug is everything after the ticket number portion. Example: `workspace_doc-1318_intro-to-billing` → `GUIDE_PREFIX = "intro-to-billing"`. All output files are prefixed with `{GUIDE_PREFIX}_`. For each entry in `target_documents[]` from the JSON mapping, convert the target document `title` to a kebab-case slug. Do not add a Diataxis type prefix — the type is recorded in the `diataxis_type` frontmatter field instead. Prepend the guide name prefix. @@ -92,10 +92,10 @@ For each entry in `target_documents[]` from the JSON mapping, convert the target - type `explanation`, title `"Recurring Charges and the Billing Engine"` → `intro-to-billing_recurring-charges.md` - type `reference`, title `"Integration Options"` → `intro-to-billing_integration-options.md` -**Examples** (guide prefix `acmepay`): -- type `explanation`, title `"Understanding AcmePay Payments"` → `acmepay_understanding-payments.md` -- type `how-to`, title `"How to Integrate AcmePay with the Platform"` → `acmepay_integrate-with-platform.md` -- type `reference`, title `"AcmePay API Reference"` → `acmepay_api-reference.md` +**Examples** (guide prefix `acme-orders`): +- type `explanation`, title `"Understanding the Order Lifecycle"` → `acme-orders_order-lifecycle.md` +- type `how-to`, title `"How to Integrate Acme Orders with the Platform"` → `acme-orders_integrate-with-platform.md` +- type `reference`, title `"Acme Orders API Reference"` → `acme-orders_api-reference.md` Store each filename as you go — you'll need these for the overview doc. @@ -105,11 +105,11 @@ Run these checks on the proposed filename (stem only, no `.md`): | Check | Rule | Example fail | |---|---|---| -| Lowercase + dashes only | No uppercase, underscores, or spaces | `AcmePay-Payments`, `acmepay_payments` | -| Area prefix present | At least one segment before the first dash | `payments.md` (no prefix) | -| Length | 2–4 dash-separated segments total | `acmepay-a.md`, `acmepay-payment-api-endpoint-list.md` | -| No gerunds | No word ending in `-ing` in any segment | `acmepay-understanding-payments.md` | -| No bare type words | Descriptor is not solely `introduction` or `explanation` | `acmepay-introduction.md`, `acmepay-explanation.md` | +| Lowercase + dashes only | No uppercase, underscores, or spaces | `Acme-Orders`, `acme_orders` | +| Area prefix present | At least one segment before the first dash | `orders.md` (no prefix) | +| Length | 2–4 dash-separated segments total | `acme-a.md`, `acme-orders-api-endpoint-list.md` | +| No gerunds | No word ending in `-ing` in any segment | `acme-orders-understanding-lifecycle.md` | +| No bare type words | Descriptor is not solely `introduction` or `explanation` | `acme-orders-introduction.md`, `acme-orders-explanation.md` | If any check fails, propose a corrected filename and confirm with the user before writing. Do not write the file with an invalid name. @@ -119,7 +119,7 @@ Once all filenames are determined, infer `AREA_PREFIX` from the output filenames Examples: - Output files `webhooks-concepts.md`, `webhooks-configure.md`, `webhooks-event-reference.md` → `AREA_PREFIX = webhooks` -- Output files `caper-refunds-customer-initiated.md`, `caper-refunds-staff-initiated.md` → `AREA_PREFIX = caper-refunds` +- Output files `order-cancellations-customer-initiated.md`, `order-cancellations-staff-initiated.md` → `AREA_PREFIX = order-cancellations` **Create the guide subfolder:** @@ -152,8 +152,8 @@ For each `sections[]` entry in this target document: At the top of each typed doc, below the H1 but before the first section heading, add a one-line reader signpost appropriate to the doc type: -- **Explanation**: `> New to AcmePay? This doc explains the concepts. Ready to implement? See [How to Integrate — title](./how-to-filename).` -- **How-to**: `> New to AcmePay? Read [Understanding AcmePay — title](./explanation-filename) first. For endpoint specs, see [API Reference — title](./reference-filename).` +- **Explanation**: `> New to Acme Orders? This doc explains the concepts. Ready to implement? See [How to Integrate — title](./how-to-filename).` +- **How-to**: `> New to Acme Orders? Read [Understanding Acme Orders — title](./explanation-filename) first. For endpoint specs, see [API Reference — title](./reference-filename).` - **Reference**: `> For step-by-step instructions, see [How to Integrate — title](./how-to-filename).` - **Tutorial**: `> When you're ready to go beyond the tutorial, see [How to Integrate — title](./how-to-filename).` @@ -286,7 +286,7 @@ All files include stub frontmatter with diataxis_type and hidden: true. Source doc was not modified. What's next: - /docs-links-review docs/output/docs/{AREA_PREFIX}/ → cross-link check against The Product corpus + /docs-links-review docs/output/docs/{AREA_PREFIX}/ → cross-link check against Acme Orders corpus /docs-visuals-review docs/output/docs/{AREA_PREFIX}/ → diagram recommendations ``` @@ -294,7 +294,7 @@ What's next: ## Overview Doc Reference -The overview doc follows the same pattern as `acmepay-overview.md`. Refer to it as a style reference: +The overview doc follows the rules in `_knowledge/style-guides/diataxis/style-guide_guide-set-overview.md`. Refer to it as a style reference: ``` docs/output/docs/{AREA_PREFIX}/index.md diff --git a/pipelines/docs-pipeline/docs-grammar-spelling.md b/pipelines/docs-pipeline/docs-grammar-spelling.md index bad73ca..98e1977 100644 --- a/pipelines/docs-pipeline/docs-grammar-spelling.md +++ b/pipelines/docs-pipeline/docs-grammar-spelling.md @@ -85,7 +85,7 @@ For every glossary term that appears in the doc's prose zones, check whether it **Capitalization specifics from the glossary `usage.capitalization` field:** - Acronyms (e.g., `API`, `SDK`, `HTTP`): always fully uppercase -- Title case terms (e.g., `Payment Method`, `Authentication Token`): capitalize in prose when used as a proper concept name; lowercase when used generically +- Title case terms (e.g., `Order Status`, `Authentication Token`): capitalize in prose when used as a proper concept name; lowercase when used generically - PascalCase terms (e.g., `ProductName`, `ApiClient`): always PascalCase, never spaced or lowercased - API field names (e.g., `field_name`, `amount`): always in backticks diff --git a/pipelines/docs-pipeline/docs-links-review.md b/pipelines/docs-pipeline/docs-links-review.md index 6b3cefd..b59f12a 100644 --- a/pipelines/docs-pipeline/docs-links-review.md +++ b/pipelines/docs-pipeline/docs-links-review.md @@ -28,7 +28,7 @@ This should be a path to a **folder** or a single `.md` **file**, with an option **Required:** The `[folder-or-file-path]` parameter is mandatory. If not provided, stop and ask: "Please provide a folder or file path: `/docs-link-check [path]`" -**Primary use case:** folder path — when a large guide has been split into multiple pieces (e.g., `output/acmepay/`), run against the directory and the skill discovers all `.md` files automatically. +**Primary use case:** folder path — when a large guide has been split into multiple pieces (e.g., `output/acme-orders/`), run against the directory and the skill discovers all `.md` files automatically. --- @@ -42,7 +42,7 @@ This should be a path to a **folder** or a single `.md` **file**, with an option - **Directory**: Glob all `.md` files inside it (non-recursive is fine; use `**/*.md` if subdirs are expected). Abort if zero `.md` files found: "No markdown files found in: [path]" - **File**: Use that single file. Abort if it doesn't exist: "File not found: [path]" - For each draft file, derive `INPUT_BASENAME`: - - Get filename stem (no extension, no leading path): e.g., `acmepay-overview.md` → `acmepay-overview` + - Get filename stem (no extension, no leading path): e.g., `acme-orders-overview.md` → `acme-orders-overview` - Store the full draft file list and their basenames. ### 2. Read draft files diff --git a/pipelines/docs-pipeline/docs-pipeline.md b/pipelines/docs-pipeline/docs-pipeline.md index 38cf9ed..eafd5de 100644 --- a/pipelines/docs-pipeline/docs-pipeline.md +++ b/pipelines/docs-pipeline/docs-pipeline.md @@ -22,6 +22,18 @@ If a single path is provided that looks like a workspace (contains `docs/input/` --- +## Constants + +``` +WORKSPACE_ROOT=~/projects +SHARED_CONFIG_DIR={SHARED_CONFIG_DIR} +``` + +- `WORKSPACE_ROOT` is the folder where workspaces are created. Change it if you want them somewhere else. +- `SHARED_CONFIG_DIR` is optional. It can point at a folder of your own shared tools (for example a schema or a diagram generator). If the value is empty or still reads `{SHARED_CONFIG_DIR}`, treat it as unset and skip every step that needs it. + +--- + ## Pipeline Overview ``` @@ -53,7 +65,7 @@ TICKET_ID = first argument (e.g., TICKET-1801) SLUG = second argument (e.g., webhooks) TICKET_NUM = numeric portion of TICKET_ID PROJECT_NAME = "workspace_doc-{TICKET_NUM}_{SLUG}" -PROJECT_PATH = ~/projects/{PROJECT_NAME} +PROJECT_PATH = {WORKSPACE_ROOT}/{PROJECT_NAME} # WORKSPACE_ROOT is defined in the Constants section below ``` ### 0b. Check for existing workspace @@ -66,8 +78,8 @@ If `PROJECT_PATH` already exists: 5. Skip to the workspace summary below. If `PROJECT_PATH` does not exist: -1. Run the full `/docs-workspace-setup` process: create directory, git init, directory tree, shared resource symlinks, CLAUDE.md, README.md, .gitignore. -2. Search `{YOUR_DOCS_REPO_PATH}` for a file matching the slug and copy it to `docs/input/`. +1. Run the full `/docs-workspace-setup` process: create directory, git init, directory tree, copy of `_knowledge/`, CLAUDE.md, README.md, .gitignore. +2. If `{YOUR_DOCS_REPO_PATH}` is configured (it does not start with `{`), search it for a file matching the slug and copy it to `docs/input/`. Otherwise tell the user to copy the source doc into `docs/input/` by hand. ### 0c. Workspace summary @@ -104,15 +116,15 @@ If both exist: **Follow the complete `/docs-diataxis-audit` process** (`docs-diataxis-audit.md`). Read that skill file and execute all steps. Do not abbreviate or skip steps. -The audit skill produces three mandatory outputs — all three must exist before Stage 1 is complete: +The audit skill produces two mandatory outputs and one optional output. The report and the mapping must exist before Stage 1 is complete: 1. **Audit report** (`{GUIDE_NAME}_audit-report.md`) — full analysis with content breakdown, boundary violations, and restructuring recommendations -2. **JSON mapping** (`{GUIDE_NAME}_mapping.json`) — section-level mapping with hash IDs following the schema at `_shared/schemas/diataxis-audit-mapping/schema.json` -3. **SVG visualizations** (`{GUIDE_NAME}_00-overview.svg`, `{GUIDE_NAME}_01-*.svg`, ...) — generated via `node _shared/tools/diataxis-mapper/generate-svg.js --multi` +2. **JSON mapping** (`{GUIDE_NAME}_mapping.json`) — section-level mapping with hash IDs following the structure in the audit skill +3. **SVG visualizations** (`{GUIDE_NAME}_00-overview.svg`, `{GUIDE_NAME}_01-*.svg`, ...) — optional, generated only if the optional diagram tool in `{SHARED_CONFIG_DIR}` is installed -`{GUIDE_NAME}` is the slug from the workspace folder name (e.g., `configure-webhooks` from `workspace-doc-1318-configure-webhooks`). All output files in the workspace (except `docs/input/`) must be prefixed with this guide name. +`{GUIDE_NAME}` is the slug from the workspace folder name (e.g., `configure-webhooks` from `workspace_doc-1318_configure-webhooks`). All output files in the workspace (except `docs/input/`) must be prefixed with this guide name. -**Do not proceed to the audit summary until all three outputs exist.** If SVG generation fails, note the error but still require the report and mapping before continuing. +**Do not proceed to the audit summary until the report and the mapping exist.** The SVGs are optional: if they are skipped or fail, note it and continue. After the audit, determine the split recommendation: - **No split needed** — the doc is cleanly one Diataxis type diff --git a/pipelines/docs-pipeline/docs-publish.md b/pipelines/docs-pipeline/docs-publish.md index ffe3a8e..9ef8810 100644 --- a/pipelines/docs-pipeline/docs-publish.md +++ b/pipelines/docs-pipeline/docs-publish.md @@ -54,18 +54,18 @@ For each `.md` in `DOCS_DIR`, check the filename stem against these rules: | Check | Rule | Example fail | |---|---|---| -| Lowercase + dashes only | No uppercase, underscores, or spaces | `AcmePay-Payments`, `acmepay_payments` | -| Area prefix present | At least one segment before the first dash | `payments.md` | -| Length | 2–4 dash-separated segments total | `acmepay-a.md`, `acmepay-payment-api-endpoint-list.md` | -| No gerunds | No segment ending in `-ing` | `acmepay-understanding-payments.md` | -| No bare type words | Stem is not solely `{area}-introduction` or `{area}-explanation` | `acmepay-introduction.md` | +| Lowercase + dashes only | No uppercase, underscores, or spaces | `Acme-Orders`, `acme_orders` | +| Area prefix present | At least one segment before the first dash | `orders.md` | +| Length | 2–4 dash-separated segments total | `acme-a.md`, `acme-orders-api-endpoint-list.md` | +| No gerunds | No segment ending in `-ing` | `acme-orders-understanding-lifecycle.md` | +| No bare type words | Stem is not solely `{area}-introduction` or `{area}-explanation` | `acme-orders-introduction.md` | If any file fails, stop and list all offenders: ``` ❌ Filename convention failed — fix before publishing: - acmepay-understanding-payments.md → gerund ("understanding") in descriptor - acmepay-introduction.md → bare type word as descriptor + acme-orders-understanding-lifecycle.md → gerund ("understanding") in descriptor + acme-orders-introduction.md → bare type word as descriptor Rename and re-run. ``` @@ -225,7 +225,7 @@ If errors are found, fix them before continuing: - **MD025 (multiple H1):** The H1 strip above should prevent this. If it persists, check for a leftover `# ` line. - **MD001 (heading increment):** Fix heading levels so they increment by one (e.g., `##` → `###`, not `##` → `####`). - **MD040 (code fence language):** Add a language tag to bare code fences. Use `text` for plain output, `json` for JSON, etc. -- **MD051 (link fragment):** Fix broken anchor links. Markdown anchors strip `/` chars entirely (e.g., `/api/acmepay/categories/` → `apiacmepaycategories`). +- **MD051 (link fragment):** Fix broken anchor links. Markdown anchors strip `/` chars entirely (e.g., `/api/orders/categories/` → `apiorderscategories`). Show the lint results. If clean, continue. If errors remain after auto-fix, stop and list them. diff --git a/pipelines/docs-pipeline/docs-sme-review.md b/pipelines/docs-pipeline/docs-sme-review.md index 51116df..5682e9b 100644 --- a/pipelines/docs-pipeline/docs-sme-review.md +++ b/pipelines/docs-pipeline/docs-sme-review.md @@ -63,7 +63,7 @@ This should be a path to a **folder** or a single `.md` **file**, with an option - If the file is missing, stop with error: "Product KB not found at _knowledge/product-kb/ — populate the placeholder files before running SME review." - Check the `extracted:` frontmatter date. If it is more than 90 days old, include a warning in every report header: "Product KB last extracted [date] (>90 days ago) — findings may be stale. Re-run extraction before acting on domain accuracy flags." - Then load the three core KB files for domain accuracy checks: - - `./_knowledge/product-kb/integration-types.md` (scopes, capabilities, credit routing) + - `./_knowledge/product-kb/integration-types.md` (scopes, capabilities, limits) - `./_knowledge/product-kb/endpoints.md` (API surface, params, responses) - `./_knowledge/product-kb/domain-models.md` (objects, lifecycles, relationships) - Load additional KB files based on what the draft content covers: @@ -76,7 +76,9 @@ This should be a path to a **folder** or a single `.md` **file**, with an option Build a lightweight index of all published doc titles to check for naming collisions. -Do a fresh shallow clone of the docs repo: +**Optional step.** If `{YOUR_ORG}` or `{YOUR_DOCS_REPO}` still reads as a placeholder (it starts with `{`), or `gh` is not installed or not logged in, skip this whole step. Set `CORPUS_TMP` to unset, print "Naming-collision check skipped: no docs repo configured" in the report header, and skip Category C in step 5. + +Otherwise do a fresh shallow clone of the docs repo: ```bash mktemp -d /tmp/docs-corpus-XXXXXX @@ -178,7 +180,7 @@ See **Report Format** below. ### 9. Clean up and display summary -Remove the temp corpus clone: +Remove the temp corpus clone (only if step 4 created one): ```bash rm -r CORPUS_TMP_PATH ``` @@ -189,7 +191,7 @@ Print the summary: SME review complete. Draft files analyzed: [N] -Corpus titles indexed: [N] +Corpus titles indexed: [N] (or "skipped") Product model verified: [date] Reports: @@ -318,7 +320,7 @@ For sections with no findings, show the `> No [category] found.` line and skip t | Directory has no `.md` files | Stop: "No markdown files found in: [path]" | | Draft file >1500 lines | Note in report header; continue | | Product KB missing | Stop: "Product KB not found" | -| Corpus clone fails | Stop: "Failed to clone docs repo. Check gh auth and network." | +| Corpus clone fails or no docs repo configured | Skip Category C, note "Naming-collision check skipped" in the report header, continue | | Title index file unreadable | Skip it; note count of skipped files | | Output directory creation fails | Stop: "Cannot create output directory" | | Report write fails | Stop: "Cannot write report: [path]" | diff --git a/pipelines/docs-pipeline/docs-style-check-human.md b/pipelines/docs-pipeline/docs-style-check-human.md index 0f72e02..52ab405 100644 --- a/pipelines/docs-pipeline/docs-style-check-human.md +++ b/pipelines/docs-pipeline/docs-style-check-human.md @@ -9,7 +9,7 @@ allowed-tools: [Read, Write, Edit, Glob, Bash] Final editing pass on one or more docs to detect and rewrite AI writing patterns. Applies every rule from the "Write Like a Human" style guide. Edits docs in place. Produces an audit report summarizing findings and fixes. -This is the last style pass in the pipeline. Run it after `/docs-style-check-structure` (structure) and `/docs-style-check-voice` (The Product conventions) so it operates on settled prose. +This is the last style pass in the pipeline. Run it after `/docs-style-check-structure` (structure) and `/docs-style-check-voice` (Acme Orders conventions) so it operates on settled prose. ## Arguments @@ -24,7 +24,7 @@ This should be a path to a **folder** (all `.md` files inside) or a single `.md` ## Constants ``` -STYLE_GUIDE=~/projects/example-docs-repo/_extras/style-guides/write-like-a-human/style-guide_write-like-a-human.md +STYLE_GUIDE=./_knowledge/style-guides/write-like-a-human/style-guide_write-like-a-human.md ``` --- @@ -160,7 +160,7 @@ For each doc, work through the checks in the exact order specified by the style **What to find:** significant, crucial, essential, effective, optimal, comprehensive, important, powerful, key, major, fundamental, core -**Fix:** Ask what specifically makes it [adjective]. Replace with the specific answer. "This is a significant part of the system" → "This determines whether the payment captures or fails." +**Fix:** Ask what specifically makes it [adjective]. Replace with the specific answer. "This is a significant part of the system" → "This determines whether the order is created or rejected." #### Pass 14: Passive voice @@ -190,7 +190,7 @@ Track every edit: `{filename}: {what changed}`. Write to the `_process/style-audit/` directory relative to the project's output root. Resolve the output root by walking up from the input path until you find a directory containing `_process/` (or create `_process/style-audit/` as a sibling of the docs folder). -**Filename:** `style-audit-human-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `caper-refunds`) +**Filename:** `style-audit-human-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `order-cancellations`) For a single file input, use the filename without extension instead of folder name. diff --git a/pipelines/docs-pipeline/docs-style-check-structure.md b/pipelines/docs-pipeline/docs-style-check-structure.md index b0f6f52..a4c3dcb 100644 --- a/pipelines/docs-pipeline/docs-style-check-structure.md +++ b/pipelines/docs-pipeline/docs-style-check-structure.md @@ -24,7 +24,7 @@ This should be a path to a **folder** (all `.md` files inside) or a single `.md` ## Constants ``` -STYLE_GUIDES_DIR=~/projects/example-docs-repo/_extras/style-guides/diataxis +STYLE_GUIDES_DIR=./_knowledge/style-guides/diataxis ``` | `diataxis_type` | Style guide file | @@ -221,7 +221,7 @@ Track every edit: `{filename}: {what changed}`. Write to the `_process/style-audit/` directory relative to the project's output root. Resolve the output root by walking up from the input path until you find a directory containing `_process/` (or create `_process/style-audit/` as a sibling of the docs folder). -**Filename:** `style-audit-diataxis-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `caper-refunds`) +**Filename:** `style-audit-diataxis-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `order-cancellations`) For a single file input, use the filename without extension instead of folder name. diff --git a/pipelines/docs-pipeline/docs-style-check-voice.md b/pipelines/docs-pipeline/docs-style-check-voice.md index 3f1c490..53e27d0 100644 --- a/pipelines/docs-pipeline/docs-style-check-voice.md +++ b/pipelines/docs-pipeline/docs-style-check-voice.md @@ -24,7 +24,7 @@ This should be a path to a **folder** (all `.md` files inside) or a single `.md` ## Constants ``` -STYLE_GUIDE=./_knowledge/style-guides/style-guide.md +STYLE_GUIDE=./_knowledge/style-guides/general/style-guide_general.md ``` --- @@ -155,7 +155,7 @@ Track every edit: `{filename}: {what changed}`. Write to the `_process/style-audit/` directory relative to the project's output root. Resolve the output root by walking up from the input path until you find a directory containing `_process/` (or create `_process/style-audit/` as a sibling of the docs folder). -**Filename:** `style-audit-general-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `caper-refunds`) +**Filename:** `style-audit-general-{folder-name}.md` (where `{folder-name}` is the input folder's basename, e.g. `order-cancellations`) For a single file input, use the filename without extension instead of folder name. diff --git a/pipelines/docs-pipeline/docs-visuals-review.md b/pipelines/docs-pipeline/docs-visuals-review.md index 0a1d0c7..3e34eab 100644 --- a/pipelines/docs-pipeline/docs-visuals-review.md +++ b/pipelines/docs-pipeline/docs-visuals-review.md @@ -60,7 +60,7 @@ For each doc (or the doc set as a whole if a folder): - Introduction → any first-time reader; both engineers and PMs - Tutorial → hands-on learner, following along -Keep personas to 2–3 max. Be specific: "payment engineer" not "developer." +Keep personas to 2–3 max. Be specific: "integration engineer" not "developer." ### 4. Assess each section for visual aid candidates @@ -68,7 +68,7 @@ For each non-trivial section in each doc, assess against these patterns. A secti **High-signal candidates (rate Critical or High):** - **Multi-party flow**: 3+ parties interacting across steps (e.g., app ↔ customer browser ↔ third-party API), especially with redirects or async steps. → Mermaid sequence diagram -- **Decision tree with consequences**: Branching logic where the wrong branch has a real cost (failed transaction, incorrect settlement, data loss). 2+ branches, each with distinct outcomes. → Mermaid flowchart +- **Decision tree with consequences**: Branching logic where the wrong branch has a real cost (failed order, incorrect fulfillment, data loss). 2+ branches, each with distinct outcomes. → Mermaid flowchart - **Lifecycle with stages**: A named sequence of phases where each phase feeds the next, especially when a time constraint (expiry, deadline) is attached. → Mermaid flowchart or stateDiagram - **Error-prone calculation in prose**: A math/proration example described only in words, where the reader must hold intermediate values in their head to follow it. → Annotated table or worked example @@ -138,15 +138,15 @@ For every diagram implemented: 1. **Mermaid diagrams** → save as `.md` file with a fenced ```` ```mermaid ```` code block 2. **Non-Mermaid visuals** (tables, worked examples) → save as `.md` file -Using `.md` (not `.mermaid` or `.mmd`) ensures the file can be previewed in Cursor with Command+Shift+V via the `bierner.markdown-mermaid` extension. +Using `.md` (not `.mermaid` or `.mmd`) ensures the file can be previewed in any Markdown preview that supports Mermaid (for example VS Code with the `bierner.markdown-mermaid` extension). **File location:** `docs/output/_process/visual-audit/diagrams/` - Create if missing: `mkdir -p docs/output/_process/visual-audit/diagrams/` **File naming:** Descriptive kebab-case slug matching the diagram's content, not a ticket number: -- ✅ `balance-session-capture-flow.md` -- ✅ `straddle-rules.md` -- ✅ `discount-proration-mixed-cart.md` +- ✅ `order-session-flow.md` +- ✅ `cancellation-rules.md` +- ✅ `discount-proration-mixed-order.md` - ❌ `ticket-1204-diagram-1.md` **File content for all `.md` diagram files** — include a plain markdown header, then wrap Mermaid in a fenced code block. Do not include a ticket ID in the file: @@ -160,7 +160,7 @@ Used in: `[filename]`, §[Section heading] ``` ``` -**Dollar signs in prose:** Escape with `\$` in all inline prose text (e.g., `\$10 off a \$100 cart`). Dollar signs inside table cells render correctly and do not need escaping. Unescaped `$...$` pairs in prose are parsed as LaTeX math delimiters by VS Code preview and other renderers. +**Dollar signs in prose:** Escape with `\$` in all inline prose text (e.g., `\$10 off a \$100 order`). Dollar signs inside table cells render correctly and do not need escaping. Unescaped `$...$` pairs in prose are parsed as LaTeX math delimiters by VS Code preview and other renderers. **Line breaks in Mermaid nodes:** Use `
` for line breaks inside Mermaid diagram node labels. `\n` and `
` do not work in Mermaid syntax. @@ -181,7 +181,7 @@ Below you'll find prioritized recommendations, split into diagrams and images an ## Who reads these docs -[2–4 sentences. Name the personas (by role), what they're trying to do, and where they typically enter the doc set. Be specific — "payment engineer building their first AcmePay integration" not "developers."] +[2–4 sentences. Name the personas (by role), what they're trying to do, and where they typically enter the doc set. Be specific — "integration engineer building their first Acme Orders integration" not "developers."] --- @@ -232,7 +232,7 @@ Screenshots, UI mockups, architecture illustrations, and anything that needs out [Include only notable skips — things where a visual might seem obvious but isn't warranted. Omit trivially short or lookup-only sections.] ``` -**Voice:** Do not mention AI or automation tools. "The Product documentation team's structured conversion process" is the right framing for the intro sentence. +**Voice:** Do not mention AI or automation tools. "Acme Orders documentation team's structured conversion process" is the right framing for the intro sentence. **Ordering within the report:** 1. Diagrams first, then images @@ -267,7 +267,7 @@ Use these Mermaid diagram types as defaults. Recommend a graphic image only when **High** — meets one or more: - Flow involves 3+ parties or 5+ steps, especially with redirects, async callbacks, or time constraints -- Decision tree where misunderstanding a branch causes a real failure (wrong API call, incorrect settlement, data loss) +- Decision tree where misunderstanding a branch causes a real failure (wrong API call, incorrect fulfillment, data loss) - Math or proration in prose where the reader must hold multiple intermediate values in their head **Medium** — meets one or more: diff --git a/pipelines/docs-pipeline/docs-work-verify.md b/pipelines/docs-pipeline/docs-work-verify.md index c218f01..75712f7 100644 --- a/pipelines/docs-pipeline/docs-work-verify.md +++ b/pipelines/docs-pipeline/docs-work-verify.md @@ -166,8 +166,9 @@ Then show "Files changed:" list. ### 10. Linear actions -If `LINEAR_TICKET_ID` was found and PR is merged, output both blocks as plain markdown (no code block): +If `LINEAR_TICKET_ID` was found and PR is merged, output both blocks below as plain markdown (no code block around your output). The fence here only keeps the template links from rendering as links in this file: +```text ───────────────────────────────────────────────────── 💬 Want to add a comment to [TICKET-XXXX]({YOUR_ISSUE_TRACKER}/TICKET-XXXX)? @@ -179,6 +180,7 @@ Reply "yes" to post it, or edit the draft above. 🔔 Don't forget to mark [TICKET-XXXX]({YOUR_ISSUE_TRACKER}/TICKET-XXXX) as Done if it isn't already. ───────────────────────────────────────────────────── +``` If no ticket found or PR is not merged: skip silently. diff --git a/pipelines/docs-pipeline/docs-workspace-setup.md b/pipelines/docs-pipeline/docs-workspace-setup.md index 83095b8..7023f12 100644 --- a/pipelines/docs-pipeline/docs-workspace-setup.md +++ b/pipelines/docs-pipeline/docs-workspace-setup.md @@ -1,6 +1,6 @@ --- name: docs-workspace-setup -description: Create or reuse a documentation workspace for a Diataxis guide audit and improvement. Sets up the project directory, TOOLBOX symlinks, CLAUDE.md, directory tree, and Obsidian note. +description: Create or reuse a documentation workspace for a Diataxis guide audit and improvement. Sets up the project directory, a copy of the knowledge files, CLAUDE.md, the directory tree, and an optional project note. argument-hint: --- @@ -21,10 +21,17 @@ The user provided: $ARGUMENTS ## Constants ``` -TOOLBOX=~/projects/TOOLBOX -VAULT={YOUR_VAULT_PATH} +WORKSPACE_ROOT=~/projects +PIPELINE_DIR={YOUR_PIPELINE_DIR} +SHARED_CONFIG_DIR={SHARED_CONFIG_DIR} +NOTES_DIR={NOTES_DIR} ``` +- `WORKSPACE_ROOT` is the folder where workspaces are created. Change it if you want them somewhere else. +- `PIPELINE_DIR` is the absolute path of the `docs-pipeline` folder that holds `_knowledge/` and `workspace-gitignore.template`. The install steps in `SETUP.md` fill it in for you. +- `SHARED_CONFIG_DIR` and `NOTES_DIR` are optional. `SHARED_CONFIG_DIR` can point at a folder of your own shared tools and agent instructions. `NOTES_DIR` can point at a notes folder (for example an Obsidian vault) where a project note is written. If a value is empty or still reads `{SHARED_CONFIG_DIR}` or `{NOTES_DIR}`, treat it as unset and skip every step that needs it. +- If `PIPELINE_DIR` still reads `{YOUR_PIPELINE_DIR}`, or `{PIPELINE_DIR}/_knowledge/` does not exist, stop: `"PIPELINE_DIR is not set. Set it to the docs-pipeline folder (see SETUP.md, Install)."` + --- ## Step 1 — Parse arguments and derive paths @@ -34,7 +41,7 @@ TICKET_ID = $ARGUMENTS[0] # e.g., TICKET-1801 SLUG = $ARGUMENTS[1] # e.g., webhooks TICKET_NUM = numeric portion of TICKET_ID # e.g., 1801 PROJECT_NAME = "workspace_doc-{TICKET_NUM}_{SLUG}" -PROJECT_PATH = ~/projects/{PROJECT_NAME} +PROJECT_PATH = {WORKSPACE_ROOT}/{PROJECT_NAME} ``` Normalize: lowercase ticket prefix in folder name (`doc-` not `DOC-`), slug in kebab-case. No spaces anywhere in the folder name — use underscores as separators. @@ -45,7 +52,7 @@ Normalize: lowercase ticket prefix in folder name (`doc-` not `DOC-`), slug in k 2. Verify the directory tree exists (`docs/input/`, `docs/output/`, etc.). Create any missing subdirectories. 3. Check if a source doc exists in `docs/input/`. If yes, print the filename. If no, print: `"No source doc in docs/input/ yet."` 4. Check if an audit exists in `docs/output/_process/diataxis-audit/`. If yes, print: `"Audit already completed."` If no, print: `"No audit yet."` - 5. Skip to Step 10 (print summary) — do not recreate files, symlinks, or Obsidian notes. + 5. Skip to Step 10 (print summary) — do not recreate files, links, or project notes. --- @@ -63,9 +70,10 @@ Create guide workspace: This will: - Create project directory with docs tree - git init - - Add 5 TOOLBOX symlinks + - Copy the _knowledge/ folder from PIPELINE_DIR + - Link SHARED_CONFIG_DIR as _shared (only if it is set) - Create CLAUDE.md, README.md, .gitignore - - Create Obsidian project note + - Create a project note (only if NOTES_DIR is set) Proceed? (y/n) ``` @@ -96,19 +104,23 @@ mkdir -p "{PROJECT_PATH}/docs/output/docs" --- -## Step 5 — Create TOOLBOX symlinks (5 symlinks) +## Step 5 — Copy the knowledge files and link the optional shared folder + +The skills read `./_knowledge/` relative to the workspace, so the workspace needs its own copy. + +```bash +cp -R "{PIPELINE_DIR}/_knowledge" "{PROJECT_PATH}/_knowledge" +``` + +Skip if `{PROJECT_PATH}/_knowledge` already exists. Never overwrite it. -For each symlink, skip if it already exists. +**Optional shared folder.** Only if `SHARED_CONFIG_DIR` is set and the folder exists: -| In project | Points to | -|---|---| -| `AGENTS.md` | `{TOOLBOX}/AGENTS.md` | -| `_shared/` | `{TOOLBOX}/_shared` | -| `.cursor/rules/` | `{TOOLBOX}/.cursor/rules` | -| `.cursor/commands/` | `{TOOLBOX}/.cursor/commands` | -| `.cursor/plans/` | `{TOOLBOX}/.cursor/plans` | +```bash +ln -s "{SHARED_CONFIG_DIR}" "{PROJECT_PATH}/_shared" +``` -Create `.cursor/` directory first: `mkdir -p "{PROJECT_PATH}/.cursor"` +Skip if `{PROJECT_PATH}/_shared` already exists. If `SHARED_CONFIG_DIR` is unset, skip this whole link and print: `"No shared config folder set, skipping _shared link."` --- @@ -131,7 +143,7 @@ Documentation workspace for auditing and restructuring the {SLUG} guide using th **Commit after every step.** Each step produces trackable output; commit it so diffs are reviewable. -**Parallel sessions:** Ben often runs two Claude terminals on the same workspace. Before starting any stage, run `git log --oneline | head -5` to check for commits from the other session. If a stage is already committed, skip it. +**Parallel sessions:** If you run two sessions on the same workspace, check what the other one has done first. Before starting any stage, run `git log --oneline | head -5` to check for commits from the other session. If a stage is already committed, skip it. 1. Place source doc in `docs/input/` → commit 2. Run `/docs-diataxis-audit docs/input/{source-filename}.md` → commit @@ -139,13 +151,14 @@ Documentation workspace for auditing and restructuring the {SLUG} guide using th 4. Run `/docs-style-check-structure docs/output/docs/` for structural style compliance → commit 5. Run `/docs-style-check-voice docs/output/docs/` for voice/tone/formatting → commit 6. Run `/docs-style-check-human docs/output/docs/` for AI pattern cleanup → commit -7. Run `/docs-grammar-spelling docs/output/docs/` for grammar, spelling, and terminology → commit -8. Run `/docs-visuals-review docs/output/docs/` for visual aid recommendations → commit -9. Run `/docs-links-review docs/output/docs/` for cross-link check → commit -10. Run `/docs-sme-review docs/output/docs/` for domain accuracy and reader journey → commit -11. Run `/docs-changes-list` to generate editorial record → commit -12. Run `/docs-decision-checkpoint` to resolve all recommendations → commit -13. Run `/docs-publish docs/output [target-path]` to create branch + PR +7. Run `/docs-readability-check docs/output/docs/` for reading level and dense sentences → commit +8. Run `/docs-grammar-spelling docs/output/docs/` for grammar, spelling, and terminology → commit +9. Run `/docs-visuals-review docs/output/docs/` for visual aid recommendations → commit +10. Run `/docs-links-review docs/output/docs/` for cross-link check → commit +11. Run `/docs-sme-review docs/output/docs/` for domain accuracy and reader journey → commit +12. Run `/docs-changes-list` to generate editorial record → commit +13. Run `/docs-decision-checkpoint` to resolve all recommendations → commit +14. Run `/docs-publish docs/output [target-path]` to create branch + PR ## Structure @@ -161,14 +174,15 @@ docs/ docs/ # Final split output docs ``` -## Shared Resources +## Knowledge files -Access via `_shared/` symlink (points to `TOOLBOX/_shared/`): +Copied into this workspace from the pipeline folder: - Style guides: `_knowledge/style-guides/` - Glossary: `_knowledge/glossary.yaml` -- Tools: `_shared/tools/` -- Audit log: `_shared/log/audit.log` +- Product knowledge base: `_knowledge/product-kb/` + +If a shared config folder was set, it is linked as `_shared/`. ``` ### README.md @@ -183,38 +197,31 @@ Write `{PROJECT_PATH}/README.md`: ### .gitignore -Copy from `{TOOLBOX}/_shared/templates/.gitignore`. +Copy `{PIPELINE_DIR}/workspace-gitignore.template` to `{PROJECT_PATH}/.gitignore`. Skip if `.gitignore` already exists. ### .git/info/exclude Write `{PROJECT_PATH}/.git/info/exclude`: ``` -# TOOLBOX symlinks -.cursor/ +# Optional shared config link _shared -AGENTS.md ``` --- -## Step 7 — Create Obsidian project note +## Step 7 — Create the project note (optional) + +Skip this whole step if `NOTES_DIR` is unset, and print: `"No notes folder set, skipping project note."` -Check if `{VAULT}/projects/{PROJECT_NAME}.md` exists. If it does, skip. +Check if `{NOTES_DIR}/{PROJECT_NAME}.md` exists. If it does, skip. If it doesn't, write: ```markdown --- -tags: - - project - - active created: {today YYYY-MM-DD} updated: {today YYYY-MM-DD} -github: "" -readme: "{PROJECT_PATH}/README.md" -related: [] -proj-ids: [] ticket: {TICKET_ID} --- @@ -224,48 +231,19 @@ ticket: {TICKET_ID} ## Links -- **README:** `= this.readme` +- **README:** {PROJECT_PATH}/README.md - **Ticket:** [{TICKET_ID}]({YOUR_TICKET_URL}/{TICKET_ID}) -- **Related:** `= this.related` ## Changelog -- {today YYYY-MM-DD} — Created via /docs-workspace-setup. - ---- - -#### Board Tasks - -```dataviewjs -const ids = dv.current().file.frontmatter["proj-ids"] || []; -if (!ids.length) { dv.paragraph("*No linked tasks.*"); return; } - -const board = await dv.io.load("_tracking/project-board.md"); -const lines = board.split("\n"); -const open = [], done = []; - -for (const id of ids) { - const line = lines.find(l => l.includes(`] ${id}:`)); - if (!line) continue; - const isDone = /^\s*- \[x\]/i.test(line); - const title = line - .replace(/^\s*-\s*\[.\]\s*/, "") - .replace(/\s*→\s*\[\[.*?\]\].*$/, "") - .trim(); - (isDone ? done : open).push(`${id} — ${title}`); -} - -if (open.length) { dv.paragraph("**Open**"); dv.list(open); } -if (done.length) { dv.paragraph("**Closed**"); dv.list(done.map(t => `~~${t}~~`)); } -if (!open.length && !done.length) { dv.paragraph("*No tasks found for: " + ids.join(", ") + "*"); } -` `` ` +- {today YYYY-MM-DD}: Created via /docs-workspace-setup. ``` --- ## Step 8 — Copy source doc (optional auto-fetch) -Search `{YOUR_DOCS_REPO_PATH}` for a file matching the slug: +If `{YOUR_DOCS_REPO_PATH}` still reads as a placeholder (it starts with `{`), skip this step and print: `"No docs repo configured. Copy the source doc into docs/input/ manually."` Otherwise search `{YOUR_DOCS_REPO_PATH}` for a file matching the slug: ```bash find {YOUR_DOCS_REPO_PATH} -name "{SLUG}.md" -type f @@ -281,13 +259,15 @@ If found, copy it to `{PROJECT_PATH}/docs/input/`. If not found, print: **Important:** Do not use `cd && git`. Use `git -C` with absolute paths. Each command is a separate tool call. ```bash -git -C "{PROJECT_PATH}" add CLAUDE.md README.md .gitignore +git -C "{PROJECT_PATH}" add CLAUDE.md README.md .gitignore _knowledge ``` ```bash git -C "{PROJECT_PATH}" commit -m "docs: scaffold guide workspace for {TICKET_ID}" ``` +If the commit fails because git does not know who you are, stop and print: `"Set your git identity first: git config --global user.name and user.email. Then re-run."` + --- ## Step 10 — Print summary @@ -303,12 +283,11 @@ Done. - .gitignore - .git/info/exclude - Symlinks: - - AGENTS.md → TOOLBOX - - _shared/ → TOOLBOX - - .cursor/rules/ → TOOLBOX - - .cursor/commands/ → TOOLBOX - - .cursor/plans/ → TOOLBOX + Knowledge files: + - _knowledge/ (copied from {PIPELINE_DIR}) + + Links: + - _shared/ → {SHARED_CONFIG_DIR} (only if set) Directories: - docs/input/ @@ -318,7 +297,7 @@ Done. - docs/output/_process/visual-audit/diagrams/ - docs/output/docs/ - Obsidian: {VAULT}/projects/{PROJECT_NAME}.md + Project note: {NOTES_DIR}/{PROJECT_NAME}.md (only if NOTES_DIR is set) Next step: copy the source doc into docs/input/ and run `/docs-pipeline` or `/docs-diataxis-audit`. ``` @@ -328,8 +307,5 @@ Next step: copy the source doc into docs/input/ and run `/docs-pipeline` or `/do ## Notes - All operations are idempotent — safe to re-run -- TOOLBOX path: `~/projects/TOOLBOX` -- Obsidian vault: set `VAULT` constant at the top to your vault path - Never overwrite existing files -- No MISTAKES_TO_AVOID.md symlink (retired) - **Bash safety:** Never use `cd &&` or compound commands. Use absolute paths and `git -C`. One command per Bash tool call. diff --git a/pipelines/docs-pipeline/sample/acme-orders-cancellations.md b/pipelines/docs-pipeline/sample/acme-orders-cancellations.md new file mode 100644 index 0000000..9870a73 --- /dev/null +++ b/pipelines/docs-pipeline/sample/acme-orders-cancellations.md @@ -0,0 +1,35 @@ + + +# Canceling orders in Acme Orders + +Let's dive in! In this guide, we will explore the exciting world of canceling orders with the Acme Orders API. It's a robust, powerful way to manage your customers' orders — and it's easier than you might think. + +## What a cancellation is + +A cancellation moves an order to the `canceled` status. Acme Orders keeps the order record so that you can still look it up later, and it releases any stock that was reserved for the order. Cancellations exist because customers change their minds, and because the same order record is used for invoicing, so a clean status trail matters. + +You can cancel any order, even one that has already been paid. Paid orders are refunded automatically. + +## How to cancel an order + +1. Find the `order_id` of the order you want to cancel. +2. Send a request to `POST /v1/orders/{order_id}/cancel`. +3. Check that the response has `status` set to `canceled`. + +Here is an example request: + +```bash +curl -X POST https://api.example.com/v1/orders/ord_123/cancel \ + -H 'Authorization: Bearer YOUR_API_KEY' \ + -d '{"reason":"customer_request"}' +``` + +If the order id is wrong, the API returns an error. The error is 404 and the code is `invalid_order_id`. + +## Webhooks + +Every integration type receives the `order.canceled` webhook, including the hosted order form. The webhook is sent when an order moves to `canceled`. + +## Things to know + +The API is rate limited, so don't send more than a thousand cancellation requests in a minute. Utilize the `reason` field to record why an order was canceled, as it is helpful for reporting purposes. diff --git a/pipelines/docs-pipeline/workspace-gitignore.template b/pipelines/docs-pipeline/workspace-gitignore.template new file mode 100644 index 0000000..5dd172b --- /dev/null +++ b/pipelines/docs-pipeline/workspace-gitignore.template @@ -0,0 +1,25 @@ +# Workspace .gitignore (copied in by /docs-workspace-setup) + +# Operating system files +.DS_Store +Thumbs.db + +# Editor files +.vscode/ +.idea/ +*.swp + +# Local environment and secrets +.env +.env.* + +# Logs and scratch files +*.log +tmp/ +scratch/ + +# Node tooling, if you use it +node_modules/ + +# Optional shared config link (created by /docs-workspace-setup when SHARED_CONFIG_DIR is set) +_shared diff --git a/skills/docs-readability-check/README.md b/skills/docs-readability-check/README.md new file mode 100644 index 0000000..7469716 --- /dev/null +++ b/skills/docs-readability-check/README.md @@ -0,0 +1,91 @@ +# docs-readability-check + +A Claude Code skill that checks how hard a doc is to read and rewrites the dense sentences. It estimates a reading grade level for each doc, finds the sentence patterns that make technical writing feel heavy, and fixes them without changing the vocabulary, the structure or the voice. + +It is Stage 3d of the [docs-pipeline](../../pipelines/docs-pipeline/README.md), where it runs after the "human" style pass and before the grammar pass. It also works on its own, on any folder of markdown files. + +## Command + +``` +/docs-readability-check [folder-or-file] +``` + +The path is required. A folder means every `.md` file inside it. Files under `_archive/`, `_templates/` and `_attachments/` are skipped. + +## What it does + +1. Reads each doc and works out its target grade level from the `diataxis_type` in the frontmatter (explanation and overview 10th to 11th grade, how-to and tutorial 11th to 12th, reference 12th to college freshman). A doc with no type gets the 11th to 12th grade target. +2. Scores a 250-word sample from the middle of the prose, with code, tables, callouts and diagrams removed. +3. Finds four patterns: stacked clauses, too many facts in one sentence, jargon followed by a clause that explains it, and wall paragraphs. +4. Rewrites the sentences it can fix safely, in place. Paragraphs it cannot safely rewrite are flagged for a person. +5. Scores again and writes a report with the grade level before and after, in plain labels such as "10th grade". + +It never edits tables, code blocks or callouts, and it does not add or remove information. + +## Output + +A report in `_process/style-audit/` named `readability-audit-{folder-name}.md`, relative to the project root. If the input sits inside an Obsidian vault, the report goes to `_system-audits/` in the vault instead. + +## Install + +Claude Code loads a skill from `//SKILL.md`. From the root of this repo: + +```bash +SKILLS_DIR="$HOME/.claude/skills" # use ./.claude/skills to install for one project only +mkdir -p "$SKILLS_DIR/docs-readability-check" +cp skills/docs-readability-check/SKILL.md "$SKILLS_DIR/docs-readability-check/SKILL.md" +``` + +Start a new Claude Code session and type `/docs-read`. The command should appear in the list. + +## Limits + +The grade level is an estimate from a sample, not a measurement of the whole doc. Reference docs full of technical terms will score high whatever you do, and the skill says so instead of forcing the number down. I have run it on my own documentation, not on yours. + +--- + +### Prompt for your AI model + +Paste this into any AI model, together with this document and the files it describes. + +**Understand and teach** + +```text +I have attached the README for "docs-readability-check", a Claude Code skill that rewrites dense sentences in docs. Teach it to me as if I am a technical writer who has never used it. + +1. Say in plain language what it checks and what it changes. +2. Say what it never touches. +3. Say where its report goes. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names the four sentence patterns, gives the target grade for each doc type, says tables, code blocks and callouts are never edited, and does not invent a feature or a command that is not in the README. +``` + +**Review against your own setup** + +```text +I have attached the README for "docs-readability-check". Below is a description of how I write and publish documentation. + +[PASTE a short description of your docs: who reads them, which doc types you write, and how you review changes.] + +Using only the README, tell me: +1. Which of my doc types match the doc types the README gives a target grade for, and which do not. +2. Whether the skill's target grades suit my readers. Say "my description does not say" if you cannot tell. +3. What I should check by hand after the skill runs. + +A good answer ties every point to something in my description or in the README, uses the README's own doc types and grade ranges, and does not invent a target grade for a doc type the README does not list. +``` + +**Adapt and test** + +```text +I have attached the README for "docs-readability-check". I want to try it on one doc without losing my original. + +[PASTE the file name of one short markdown doc of yours.] + +Write me a trial plan. Use the install commands and the slash command from the README. Say what I should copy first so the original is safe, what the report should contain, and one sign that the skill rewrote something it should have left alone. Do not invent commands, flags, or file paths that the README does not contain, and say where the README gives no undo step. + +A good answer uses the README's install commands and the exact command `/docs-readability-check [folder-or-file]`, tells me to work on a copy because the skill edits in place, names the report folder the README gives, and does not promise a particular grade level for my doc. +``` + +**How these prompts were checked.** PENDING_RUN_RECORD From 6864bf7219ac3d213e7822b7a622209fabfeaf23 Mon Sep 17 00:00:00 2001 From: darthrootbeer Date: Thu, 1 Oct 2026 22:24:36 -0400 Subject: [PATCH 2/5] fix(docs-pipeline): drop git exclude write and make ticket link optional Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01XV3Ggh86cf2xwUyz28XaN6 --- pipelines/docs-pipeline/docs-workspace-setup.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/pipelines/docs-pipeline/docs-workspace-setup.md b/pipelines/docs-pipeline/docs-workspace-setup.md index 7023f12..4432dde 100644 --- a/pipelines/docs-pipeline/docs-workspace-setup.md +++ b/pipelines/docs-pipeline/docs-workspace-setup.md @@ -128,7 +128,7 @@ Skip if `{PROJECT_PATH}/_shared` already exists. If `SHARED_CONFIG_DIR` is unset ### CLAUDE.md -Write `{PROJECT_PATH}/CLAUDE.md`: +Write `{PROJECT_PATH}/CLAUDE.md`. If `{YOUR_TICKET_URL}` still reads as a placeholder (it starts with `{`), write the ticket line as the plain ticket ID with no link. The `.gitignore` template already excludes the optional `_shared` link, so no `.git/info/exclude` is needed: ```markdown # Guide Workspace — {TICKET_ID}: {SLUG} @@ -199,15 +199,6 @@ Write `{PROJECT_PATH}/README.md`: Copy `{PIPELINE_DIR}/workspace-gitignore.template` to `{PROJECT_PATH}/.gitignore`. Skip if `.gitignore` already exists. -### .git/info/exclude - -Write `{PROJECT_PATH}/.git/info/exclude`: - -``` -# Optional shared config link -_shared -``` - --- ## Step 7 — Create the project note (optional) @@ -281,7 +272,6 @@ Done. - CLAUDE.md - README.md - .gitignore - - .git/info/exclude Knowledge files: - _knowledge/ (copied from {PIPELINE_DIR}) From e035975d2a47befbc5316ea81a367e256a1c1316 Mon Sep 17 00:00:00 2001 From: darthrootbeer Date: Thu, 1 Oct 2026 22:39:34 -0400 Subject: [PATCH 3/5] docs(docs-pipeline): add saved prompt runs, offline check and readability skill readme Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01XV3Ggh86cf2xwUyz28XaN6 --- pipelines/docs-pipeline/ARCHITECTURE.md | 2 +- pipelines/docs-pipeline/README.md | 11 +- pipelines/docs-pipeline/SETUP.md | 14 ++- .../docs-pipeline/tests/check_pipeline.py | 71 ++++++++++++ .../tests/prompt-runs/RC-adapt-haiku.md | 55 +++++++++ .../tests/prompt-runs/RC-adapt-sonnet.md | 65 +++++++++++ .../tests/prompt-runs/RC-review-haiku.md | 44 ++++++++ .../tests/prompt-runs/RC-review-sonnet.md | 46 ++++++++ .../tests/prompt-runs/RC-teach-haiku.md | 53 +++++++++ .../tests/prompt-runs/RC-teach-sonnet.md | 71 ++++++++++++ .../tests/prompt-runs/README-adapt-haiku.md | 78 +++++++++++++ .../tests/prompt-runs/README-adapt-sonnet.md | 69 ++++++++++++ .../tests/prompt-runs/README-review-haiku.md | 68 +++++++++++ .../tests/prompt-runs/README-review-sonnet.md | 70 ++++++++++++ .../tests/prompt-runs/README-teach-haiku.md | 60 ++++++++++ .../tests/prompt-runs/README-teach-sonnet.md | 72 ++++++++++++ .../docs-pipeline/tests/prompt-runs/README.md | 32 ++++++ .../tests/prompt-runs/SETUP-adapt-haiku.md | 33 ++++++ .../tests/prompt-runs/SETUP-adapt-sonnet.md | 41 +++++++ .../tests/prompt-runs/SETUP-glossary-haiku.md | 106 ++++++++++++++++++ .../prompt-runs/SETUP-glossary-sonnet.md | 79 +++++++++++++ .../tests/prompt-runs/SETUP-review-haiku.md | 47 ++++++++ .../tests/prompt-runs/SETUP-review-sonnet.md | 44 ++++++++ .../tests/prompt-runs/SETUP-teach-haiku.md | 57 ++++++++++ .../tests/prompt-runs/SETUP-teach-sonnet.md | 56 +++++++++ .../earlier-versions/RC-teach-haiku-v1.md | 47 ++++++++ .../earlier-versions/SETUP-adapt-haiku-v1.md | 35 ++++++ skills/docs-readability-check/README.md | 10 +- 28 files changed, 1421 insertions(+), 15 deletions(-) create mode 100644 pipelines/docs-pipeline/tests/check_pipeline.py create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-review-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-review-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-teach-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/RC-teach-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-adapt-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-adapt-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-review-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-review-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-teach-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README-teach-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/README.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-haiku.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-sonnet.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/RC-teach-haiku-v1.md create mode 100644 pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/SETUP-adapt-haiku-v1.md diff --git a/pipelines/docs-pipeline/ARCHITECTURE.md b/pipelines/docs-pipeline/ARCHITECTURE.md index 044aa11..609aef4 100644 --- a/pipelines/docs-pipeline/ARCHITECTURE.md +++ b/pipelines/docs-pipeline/ARCHITECTURE.md @@ -305,7 +305,7 @@ For each check give the action to take, the result I should see, and what a fail A good answer has exactly these four checks, does not invent commands or file names, and points out where the document is silent. ``` -**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". +**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". The answers for these prompts were not saved. | Prompt | Sonnet | Haiku | | --- | --- | --- | diff --git a/pipelines/docs-pipeline/README.md b/pipelines/docs-pipeline/README.md index eea0f63..efa912c 100644 --- a/pipelines/docs-pipeline/README.md +++ b/pipelines/docs-pipeline/README.md @@ -51,7 +51,7 @@ Each file has fill-in instructions at the top. Stage 0 copies the whole `_knowle ## Pipeline order ``` -workspace → audit → split → structure → voice → human → readability +workspace → audit → split → overview → structure → voice → human → readability → grammar → visuals → links → SME → changes → decisions → publish → verify ``` @@ -136,11 +136,10 @@ Write me a trial plan that uses only the stages that do not need a docs platform A good answer uses the real command names from the README, leaves out the publish and verify stages, describes each stage's output only as the README does, and does not predict what the stage will find in my document. ``` -**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". +**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all three after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". | Prompt | Sonnet | Haiku | | --- | --- | --- | -| Understand and teach | Pass | Pass | -| Review against your own setup | Pass | Pass. It credited the README with a phrase the README does not contain. | -| Adapt and test | Pass | Pass after a fix. The first version asked what I "should expect to see", and Haiku answered with confident predictions about a document it had never seen. The prompt now asks only for what the README says each stage produces. | - +| Understand and teach | Pass | Pass. It said the pipeline "works through seven stages", a count the README does not state. | +| Review against your own setup | Pass | Pass. It did not list the three optional placeholders, which the README describes in prose and not in the table. | +| Adapt and test | Pass | Pass | diff --git a/pipelines/docs-pipeline/SETUP.md b/pipelines/docs-pipeline/SETUP.md index 9423a21..54bf578 100644 --- a/pipelines/docs-pipeline/SETUP.md +++ b/pipelines/docs-pipeline/SETUP.md @@ -89,7 +89,9 @@ If the count is lower, the loop wrote to a different folder than the one Claude ## 4. Smoke test -This runs the pipeline on a short sample doc that ships in this folder (`sample/acme-orders-cancellations.md`, a made-up doc about a made-up product). It stops before anything is published and needs no placeholders. Run these in Claude Code: +First, an offline check that needs no model. From the root of your clone, run `python3 pipelines/docs-pipeline/tests/check_pipeline.py`. It confirms that every knowledge file the skills name exists and that the folder holds no private paths. It should print `check_pipeline: clean`. + +Then the real test. This runs the pipeline on a short sample doc that ships in this folder (`sample/acme-orders-cancellations.md`, a made-up doc about a made-up product). It stops before anything is published and needs no placeholders. Run these in Claude Code: 1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. 2. In that folder, copy the sample in: `cp "/sample/acme-orders-cancellations.md" docs/output/docs/` @@ -335,16 +337,16 @@ I have attached the setup guide for "docs-pipeline". Section 4 is a smoke test o [PASTE the file name of your doc and a one-line description of what it is about.] -Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly instead of promising a result. +Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. In the copy command, write my doc's location as ``. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. Do not predict what any stage will find in my doc. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly. A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them. ``` -**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". +**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document and any other file the prompt names, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. I re-ran all four prompts after the fresh-clone fixes on the same day, and the answers are saved in [`tests/prompt-runs/`](./tests/prompt-runs/README.md). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". | Prompt | Sonnet | Haiku | | --- | --- | --- | -| Understand and teach | Pass | Pass. It contradicted itself on whether a stage stops when a knowledge file is missing. | +| Glossary (section 5.1) | Pass | Pass | +| Understand and teach | Pass | Pass. It told me to replace every placeholder before the smoke test, although section 4 says the smoke test needs none. | | Review against your own setup | Pass | Pass | -| Adapt and test | Pass, on both runs | Fail, on both runs. It wrote its own shell commands (creating files, search and replace, deleting a folder) although the prompt says to use only commands from the guide. Use a stronger model for this one. | - +| Adapt and test | Pass | Pass on the third version of the prompt. The earlier version of this prompt, which asked the model to write a smoke test from nothing, failed on Haiku on both runs because it wrote its own shell commands. The guide now has a smoke test, so the prompt adapts that one. Two further wording fixes were needed: forbid predictions about the reader's doc, and write the doc's location as ``. | diff --git a/pipelines/docs-pipeline/tests/check_pipeline.py b/pipelines/docs-pipeline/tests/check_pipeline.py new file mode 100644 index 0000000..8c56a66 --- /dev/null +++ b/pipelines/docs-pipeline/tests/check_pipeline.py @@ -0,0 +1,71 @@ +#!/usr/bin/env python3 +"""Offline check that the docs-pipeline folder is self-contained. + +Run from anywhere: python3 pipelines/docs-pipeline/tests/check_pipeline.py + +It needs no model and no network. It checks four things: +1. Every `./_knowledge/...` path a skill file names exists in this folder. +2. Every skill file has the frontmatter name the install loop relies on. +3. No file mentions a private tool, home path, or leftover setup. +4. The sample doc, the .gitignore template and the product knowledge starters ship. + +Exit code 0 means clean, 1 means problems were printed. +""" +import pathlib +import re +import sys + +HERE = pathlib.Path(__file__).resolve().parent.parent +REPO = HERE.parent.parent +READABILITY = REPO / "skills" / "docs-readability-check" + +# Words that must not appear anywhere in the shipped folders. +BANNED = [r"TOOLBOX", r"/Users/", r"~/Downloads", r"\.cursor", r"example-docs-repo", r"_extras/style-guides"] + +problems = [] + +skill_files = sorted(HERE.glob("docs-*.md")) + [READABILITY / "SKILL.md"] +TESTS = HERE / "tests" +all_files = [p for p in list(HERE.rglob("*")) + list(READABILITY.rglob("*")) + if p.is_file() and TESTS not in p.parents and p.suffix in {".md", ".yaml", ".template"}] + +# 1. knowledge paths named in skill files must exist +for f in skill_files: + for m in re.finditer(r"\./_knowledge/[A-Za-z0-9_./-]+", f.read_text(encoding="utf-8")): + target = m.group(0).rstrip(".") + if not (HERE / target[2:]).exists(): + problems.append(f"{f.name}: names {target}, which does not exist in this folder") + +# 2. frontmatter names match file names +for f in skill_files: + text = f.read_text(encoding="utf-8") + m = re.match(r"---\nname: (\S+)\n", text) + expected = f.stem if f.name != "SKILL.md" else "docs-readability-check" + if not m or m.group(1) != expected: + problems.append(f"{f.name}: frontmatter name is not {expected}") + +# 3. banned strings +for f in all_files: + text = f.read_text(encoding="utf-8") + for pat in BANNED: + if re.search(pat, text): + problems.append(f"{f.relative_to(REPO)}: contains {pat}") + +# 4. shipped starter files +for rel in ["sample/acme-orders-cancellations.md", "workspace-gitignore.template", + "_knowledge/product-kb/index.md", "_knowledge/product-kb/integration-types.md", + "_knowledge/product-kb/endpoints.md", "_knowledge/product-kb/domain-models.md", + "_knowledge/product-kb/error-codes.md", "_knowledge/product-kb/webhooks.md", + "_knowledge/product-kb/recent-changes.md", + "_knowledge/style-guides/general/style-guide_general.md"]: + if not (HERE / rel).is_file(): + problems.append(f"missing shipped file: {rel}") +if not (READABILITY / "README.md").is_file(): + problems.append("missing skills/docs-readability-check/README.md") + +if problems: + print(f"check_pipeline: {len(problems)} problem(s)") + for p in problems: + print(" " + p) + sys.exit(1) +print(f"check_pipeline: clean ({len(skill_files)} skill files, {len(all_files)} files scanned)") diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-haiku.md new file mode 100644 index 0000000..84ab4b5 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-haiku.md @@ -0,0 +1,55 @@ +# RC-adapt on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check". I want to try it on one doc without losing my original. + +webhook-retries.md + +Write me a trial plan. Use the install commands and the slash command from the README. Say what I should copy first so the original is safe, what the report should contain, and one sign that the skill rewrote something it should have left alone. Do not invent commands, flags, or file paths that the README does not contain, and say where the README gives no undo step. + +A good answer uses the README's install commands and the exact command `/docs-readability-check [folder-or-file]`, tells me to work on a copy because the skill edits in place, names the report folder the README gives, and does not promise a particular grade level for my doc. +``` + +Answer: + +# Trial Plan for docs-readability-check on webhook-retries.md + +## Step 1: Install the skill + +Run these commands from the root of your repo (or use `./.claude/skills` if you want this project only): + +```bash +SKILLS_DIR="$HOME/.claude/skills" +mkdir -p "$SKILLS_DIR/docs-readability-check" +cp skills/docs-readability-check/SKILL.md "$SKILLS_DIR/docs-readability-check/SKILL.md" +``` + +Then start a new Claude Code session and type `/docs-read` to confirm it appears. + +## Step 2: Make a safe copy + +Copy `webhook-retries.md` to a new file (e.g., `webhook-retries-trial.md`). **The skill edits in place**, so work on the copy, not the original. + +## Step 3: Run the skill + +Type: +``` +/docs-readability-check webhook-retries-trial.md +``` + +## Step 4: Check the report + +Look for a file at `_process/style-audit/readability-audit-{folder-name}.md` (relative to your project root). The report will show: +- Grade level **before** and **after** (in plain labels like "10th grade") +- The four sentence patterns it found: stacked clauses, too many facts in one sentence, jargon followed by explanatory clauses, and wall paragraphs + +## Watch for improper rewrites + +One sign the skill rewrote something it shouldn't have: **changes inside code blocks, tables, or callouts**. The README says it "never edits" these, so if you find modifications there, something went wrong. + +## Note: No undo step + +The README gives no undo or rollback step. If the skill changes something incorrectly, you'll need to restore from your copy. Keep `webhook-retries.md` untouched while you experiment on `webhook-retries-trial.md`. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-sonnet.md new file mode 100644 index 0000000..8b81b4b --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-adapt-sonnet.md @@ -0,0 +1,65 @@ +# RC-adapt on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check". I want to try it on one doc without losing my original. + +webhook-retries.md + +Write me a trial plan. Use the install commands and the slash command from the README. Say what I should copy first so the original is safe, what the report should contain, and one sign that the skill rewrote something it should have left alone. Do not invent commands, flags, or file paths that the README does not contain, and say where the README gives no undo step. + +A good answer uses the README's install commands and the exact command `/docs-readability-check [folder-or-file]`, tells me to work on a copy because the skill edits in place, names the report folder the README gives, and does not promise a particular grade level for my doc. +``` + +Answer: + +# Trial plan: docs-readability-check on `webhook-retries.md` + +## 1. Install (README commands, run from the repo root) + +```bash +SKILLS_DIR="$HOME/.claude/skills" # use ./.claude/skills to install for one project only +mkdir -p "$SKILLS_DIR/docs-readability-check" +cp skills/docs-readability-check/SKILL.md "$SKILLS_DIR/docs-readability-check/SKILL.md" +``` + +Start a new Claude Code session and type `/docs-read`. The command should appear in the list. If it doesn't, stop here, because the install didn't take. + +## 2. Copy first, then work on the copy + +The README says the skill rewrites sentences **in place**, so the original is at risk if you point it at the real file. Before running anything: + +1. Make a backup of `webhook-retries.md` somewhere the skill won't touch, and leave it alone. Any plain copy works; the README gives no copy command for this, so use your usual one. +2. Make a second copy to be the trial file, for example in a new folder of its own. Run the skill on that copy only. + +A separate folder helps in two ways. The skill accepts a folder or a file, and the report filename is built from the folder name (`readability-audit-{folder-name}.md`), so a dedicated folder keeps the report easy to find. Also avoid placing the copy under `_archive/`, `_templates/` or `_attachments/`, since the README says those are skipped. + +## 3. Run + +``` +/docs-readability-check [folder-or-file] +``` + +Replace the bracket with the path to your trial copy (the path is required). Run it once. + +## 4. What the report should contain + +The report is written to `_process/style-audit/readability-audit-{folder-name}.md`, relative to the project root. If your copy sits inside an Obsidian vault, it goes to `_system-audits/` in the vault instead. + +Per the README, it should show: +- the grade level **before** and **after**, in plain labels such as "10th grade" +- paragraphs the skill could not safely rewrite, flagged for a person + +The target grade comes from the `diataxis_type` in your doc's frontmatter. Without a type, the target is 11th to 12th grade. The README doesn't say what your doc will score, and the score is an estimate from a 250-word sample of the middle of the prose, so don't expect or require a particular result. Reference docs with many technical terms may score high regardless, and the skill is meant to say so rather than force the number down. + +## 5. A sign it rewrote something it shouldn't have + +Compare your trial copy with the backup. The README says the skill never edits tables, code blocks or callouts, and never adds or removes information. So the clearest warning sign is **any difference inside a table, a code block or a callout**. For a webhook retries doc, that means a changed retry interval, status code, header name or JSON example. A changed vocabulary, structure or voice in the prose would be a second sign, since the README says those stay the same. + +## 6. Undo + +**The README gives no undo step.** It describes no backup, dry-run, revert command or flag. Your only way back is the copy you made in step 2. If you're happy with the result, bring the changes over to the original by hand, after reviewing the differences. + +One caveat: the README's author says they have run it on their own documentation, not on yours, so treat this as a real trial. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-review-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-review-haiku.md new file mode 100644 index 0000000..2656c3d --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-review-haiku.md @@ -0,0 +1,44 @@ +# RC-review on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check". Below is a description of how I write and publish documentation. + +My readers are backend developers who integrate with a payments-free orders API. I write how-to guides, reference pages and a few conceptual pages. One colleague reviews each change. + +Using only the README, tell me: +1. Which of my doc types match the doc types the README gives a target grade for, and which do not. +2. Whether the skill's target grades suit my readers. Say "my description does not say" if you cannot tell. +3. What I should check by hand after the skill runs. + +A good answer ties every point to something in my description or in the README, uses the README's own doc types and grade ranges, and does not invent a target grade for a doc type the README does not list. +``` + +Answer: + +Looking at the README against your description: + +## 1. Doc types and README targets + +All three of your doc types match README targets: + +- **How-to guides** → README's "how-to and tutorial" (11th to 12th grade) +- **Reference pages** → README's "reference" (12th to college freshman) +- **Conceptual pages** → README's "explanation and overview" (10th to 11th grade) + +The README uses "explanation and overview" where you said "conceptual"; the intent aligns. + +## 2. Whether target grades suit your readers + +**My description does not say.** Your description names your readers (backend developers integrating a payments API) but does not say what reading level is appropriate for them. The README gives grade ranges but makes no claim about which grades fit which professional audiences. You would need to decide whether 11th-grade-to-college-level readability matches what backend developers need from your API documentation. + +## 3. What to check by hand after the skill runs + +From the README, check: + +1. **Paragraphs flagged in the report** — the README says the skill "flags for a person" sections it cannot rewrite safely. Review these first. +2. **Rewrites in reference pages specifically** — your readers are backend developers working with technical integration details. The README warns that "reference docs full of technical terms will score high whatever you do." Spot-check whether rewrites preserved the technical precision your readers need, even if the grade didn't improve much. +3. **That tables, code blocks, and callouts are unchanged** — the README says these are never edited. Scan the report to confirm the skill left them alone. +4. **Before/after grade realism** — verify the grade shift reflects actual readability gains rather than oversimplification of technical content. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-review-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-review-sonnet.md new file mode 100644 index 0000000..ad951ca --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-review-sonnet.md @@ -0,0 +1,46 @@ +# RC-review on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check". Below is a description of how I write and publish documentation. + +My readers are backend developers who integrate with a payments-free orders API. I write how-to guides, reference pages and a few conceptual pages. One colleague reviews each change. + +Using only the README, tell me: +1. Which of my doc types match the doc types the README gives a target grade for, and which do not. +2. Whether the skill's target grades suit my readers. Say "my description does not say" if you cannot tell. +3. What I should check by hand after the skill runs. + +A good answer ties every point to something in my description or in the README, uses the README's own doc types and grade ranges, and does not invent a target grade for a doc type the README does not list. +``` + +Answer: + +## 1. Doc type matches + +The README sets the target grade from the `diataxis_type` in each doc's frontmatter. + +| Your doc type | README doc type and target | Match | +|---|---|---| +| How-to guides | how-to: 11th to 12th grade | Direct match | +| Reference pages | reference: 12th to college freshman | Direct match | +| Conceptual pages | explanation and overview: 10th to 11th grade | Not a named match | + +The README never uses the word "conceptual." Explanation or overview is the closest listed type, but you would have to tag those pages that way in the frontmatter. Your description doesn't say whether you use `diataxis_type` at all. If a page has no type, the README gives it 11th to 12th grade. That would apply to all three of your doc types if none are tagged. + +## 2. Do the target grades suit your readers? + +My description does not say. You've told me your readers are backend developers integrating with an orders API. You haven't given their reading level or whether they read English as a second language, and the README doesn't say who the grades were chosen for. The README's author also says they ran it only on their own docs, not yours. + +The README does say that reference docs full of technical terms will score high whatever you do. The skill reports that rather than forcing the number down. For your reference pages, a high score is not necessarily a sign of a problem. + +## 3. What to check by hand + +- **Frontmatter types.** Confirm each page has the right `diataxis_type`, especially the conceptual pages. A wrong or missing type means the wrong target grade. +- **Tables, code blocks and callouts.** The skill never edits these, and it strips them before scoring. Parameter tables, request and response examples, and warnings in an API doc are all untouched, so review their wording yourself. +- **Flagged paragraphs.** The skill flags paragraphs it can't safely rewrite for a person. Work through them. +- **The rewrites themselves.** The skill edits in place, and the README gives no undo step. It also says it doesn't add or remove information, but you should still confirm that meaning is intact. Look at step order in how-tos and conditions or limits in reference text. Give your reviewing colleague the diff against your original, not just the final text. +- **The grade numbers.** The score comes from a 250-word sample of the middle of the prose, so it is an estimate. Read the start and end of longer pages yourself. +- **The report.** Read it in `_process/style-audit/readability-audit-{folder-name}.md`, or in `_system-audits/` if your docs sit in an Obsidian vault. Check the before and after grades against the targets above, bearing in mind the reference-page caveat in point 2. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-haiku.md new file mode 100644 index 0000000..6eff819 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-haiku.md @@ -0,0 +1,53 @@ +# RC-teach on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check", a Claude Code skill that rewrites dense sentences in docs. Teach it to me as if I am a technical writer who has never used it. + +1. Say in plain language what it checks and what it changes, and give the target grade for each doc type. +2. Say what it never touches. +3. Say where its report goes. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names the four sentence patterns, gives the target grade for each doc type, says tables, code blocks and callouts are never edited, and does not invent a feature or a command that is not in the README. +``` + +Answer: + +# What docs-readability-check does + +**In plain language:** This skill grades how hard your docs are to read by measuring against a target for each doc type. It then hunts for four specific sentence patterns that make technical writing feel dense and heavy, and rewrites those sentences to be clearer. It does not change your word choices, your doc structure, or your voice — and it adds or removes nothing. + +**The four sentence patterns it fixes:** +1. Stacked clauses (too many dependent clauses chained together) +2. Too many facts crammed into one sentence +3. Jargon introduced and then immediately explained in the same sentence +4. Wall paragraphs (very long, unbroken blocks of text) + +**Target grade levels, by doc type:** +- **Explanation & Overview:** 10th to 11th grade +- **How-to & Tutorial:** 11th to 12th grade +- **Reference:** 12th to college freshman +- **Any doc without a type in the frontmatter:** 11th to 12th grade + +--- + +## What it never touches + +Tables, code blocks, and callouts are always left alone. The skill removes them from its reading-level sample (so code doesn't skew the grade), but it never edits them. + +--- + +## Where the report goes + +The skill writes a single report file to `_process/style-audit/readability-audit-{folder-name}.md` (measured from your project root). If your docs live in an Obsidian vault, the report goes to `_system-audits/` inside the vault instead. + +--- + +## Now let me check that you understood + +**Question 1 of 3:** + +Your docs include an explanation doc that targets readers familiar with your domain. What grade level should the skill aim for when it checks that doc? + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-sonnet.md new file mode 100644 index 0000000..85ab0e9 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/RC-teach-sonnet.md @@ -0,0 +1,71 @@ +# RC-teach on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check", a Claude Code skill that rewrites dense sentences in docs. Teach it to me as if I am a technical writer who has never used it. + +1. Say in plain language what it checks and what it changes, and give the target grade for each doc type. +2. Say what it never touches. +3. Say where its report goes. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names the four sentence patterns, gives the target grade for each doc type, says tables, code blocks and callouts are never edited, and does not invent a feature or a command that is not in the README. +``` + +Answer: + +# docs-readability-check, taught from the README + +## What it checks and what it changes + +The skill measures how hard your docs are to read, then rewrites the sentences that make them heavy. It keeps your vocabulary, structure and voice as they are. + +For each doc it does this: + +1. **Sets a target grade** from the `diataxis_type` in the frontmatter: + + | Doc type | Target grade | + |---|---| + | Explanation, overview | 10th to 11th | + | How-to, tutorial | 11th to 12th | + | Reference | 12th to college freshman | + | No type in frontmatter | 11th to 12th | + +2. **Scores a sample.** It takes 250 words from the middle of the prose, with code, tables, callouts and diagrams removed. +3. **Looks for four patterns:** + - stacked clauses + - too many facts in one sentence + - jargon followed by a clause that explains it + - wall paragraphs +4. **Rewrites in place** the sentences it can fix safely. Paragraphs it can't safely rewrite are flagged for a person. +5. **Scores again** and reports the grade before and after, in plain labels like "10th grade". + +Because it edits in place, the README gives no undo step. Work from a copy or have version control ready. + +## What it never touches + +- Tables +- Code blocks +- Callouts + +It also doesn't add or remove information. Files under `_archive/`, `_templates/` and `_attachments/` are skipped entirely. + +## Where the report goes + +The report is `readability-audit-{folder-name}.md` in `_process/style-audit/`, relative to the project root. If the input is inside an Obsidian vault, it goes to `_system-audits/` in the vault instead. + +## Using it + +The command is `/docs-readability-check [folder-or-file]`. The path is required. A folder means every `.md` file inside it. + +Two limits to remember: the grade is an estimate from a sample, not a measure of the whole doc. And reference docs full of technical terms will score high regardless, and the skill says so rather than forcing the number down. + +--- + +## Check your understanding + +**Question 1 of 3:** A doc has `diataxis_type: tutorial` in its frontmatter. What grade range is the skill aiming for, and which part of the doc does it score to find the current grade? + +Answer when you're ready and I'll give you the next question. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-haiku.md new file mode 100644 index 0000000..d977a38 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-haiku.md @@ -0,0 +1,78 @@ +# README-adapt on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline". I want to try it on one short document before I trust it on a real doc set. + +It is a 60-line markdown file about resetting an API key. It lives in docs/guides/reset-api-key.md. + +Write me a trial plan that uses only the stages that do not need a docs platform: the audit, the style passes, the readability check, and the grammar check. For each stage give the exact slash command from the README, what the README says that stage produces, and one sign that the stage went wrong. Finish with the knowledge files I must fill in before I run it, and how I will know the trial worked. + +A good answer uses the real command names from the README, leaves out the publish and verify stages, describes each stage's output only as the README does, and does not predict what the stage will find in my document. +``` + +Answer: + +# Trial Plan: docs-pipeline on reset-api-key.md + +## Stage 1 — Audit + +**Command:** `/docs-diataxis-audit docs/guides/reset-api-key.md` + +**What it produces:** Classifies doc content by Diataxis type, produces audit report + JSON mapping + +**Sign it went wrong:** The stage returns an error message instead of producing the audit report + +## Stage 3a — Structure + +**Command:** `/docs-style-check-structure docs/guides/reset-api-key.md` + +**What it produces:** Checks required sections, headings, and Diataxis structural rules + +**Sign it went wrong:** The stage exits with an error or cannot read the file + +## Stage 3b — Voice + +**Command:** `/docs-style-check-voice docs/guides/reset-api-key.md` + +**What it produces:** Applies general style guide voice, tone, list formatting, and terminology rules + +**Sign it went wrong:** The stage fails to load the style guide or returns an error + +## Stage 3c — Human + +**Command:** `/docs-style-check-human docs/guides/reset-api-key.md` + +**What it produces:** Removes AI writing patterns (em dashes, filler phrases, uniform sentences) + +**Sign it went wrong:** The stage cannot process the input file or returns no output + +## Stage 3d — Readability + +**Command:** `/docs-readability-check docs/guides/reset-api-key.md` + +**What it produces:** Estimates reading grade level, finds dense sentence patterns, and rewrites them to the target level for the doc type + +**Sign it went wrong:** The stage returns an error or cannot estimate the grade level + +## Stage 3e — Grammar + +**Command:** `/docs-grammar-spelling docs/guides/reset-api-key.md` + +**What it produces:** Grammar, spelling, and domain terminology check + +**Sign it went wrong:** The stage exits with an error before completing the check + +## Knowledge Files to Fill In + +Before running the trial: + +- `_knowledge/glossary.yaml` — Fill with domain terminology, canonical forms, and common mistakes for your product +- `_knowledge/product-kb/` — Fill with your product model (integration types, API endpoints, domain objects, webhooks, error codes) +- `_knowledge/style-guides/general/style-guide_general.md` — Fill with your voice, tone, and formatting rules + +## How to Know the Trial Worked + +The trial worked if all six stages complete without errors and each stage produces output (audit report, style findings, readability findings, grammar/spelling findings). All output files should be created without tool errors or missing data. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-sonnet.md new file mode 100644 index 0000000..48eb2e8 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-adapt-sonnet.md @@ -0,0 +1,69 @@ +# README-adapt on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline". I want to try it on one short document before I trust it on a real doc set. + +It is a 60-line markdown file about resetting an API key. It lives in docs/guides/reset-api-key.md. + +Write me a trial plan that uses only the stages that do not need a docs platform: the audit, the style passes, the readability check, and the grammar check. For each stage give the exact slash command from the README, what the README says that stage produces, and one sign that the stage went wrong. Finish with the knowledge files I must fill in before I run it, and how I will know the trial worked. + +A good answer uses the real command names from the README, leaves out the publish and verify stages, describes each stage's output only as the README does, and does not predict what the stage will find in my document. +``` + +Answer: + +# Trial plan: `docs/guides/reset-api-key.md` + +The README doesn't name an output file for most stages, so where it only describes what a stage does, I quote that instead of inventing an artifact. + +## Before you start + +1. Install the skills with the loop in section 3 of SETUP.md. +2. Run the smoke test in section 4 of SETUP.md. It uses the bundled sample doc and needs no configuration. +3. Fill in the knowledge files (listed at the end). +4. Run `/docs-workspace-setup`. The README says it creates the workspace, copies in `_knowledge/`, and writes starter files. It's Stage 0 rather than one of your five, but the knowledge files are copied into the workspace here, so it has to come after you fill them in. The README doesn't show its arguments, so check SETUP.md or the skill file. + +The README says nothing moves to the next stage until a person says so, so review each stage's result before starting the next. + +## Stages, in README order + +| Stage | Command | What the README says it produces | One sign it went wrong | +|---|---|---|---| +| 1 | `/docs-diataxis-audit docs/guides/reset-api-key.md` | Classifies doc content by Diataxis type and produces an audit report plus a JSON mapping | Either the report or the JSON mapping is missing | +| 3a | `/docs-style-check-structure` | Checks required sections, headings, and Diataxis structural rules | The stage touches files other than your document | +| 3b | `/docs-style-check-voice` | Applies the general style guide's voice, tone, list formatting, and terminology rules | A change contradicts a rule you wrote in `style-guide_general.md` | +| 3c | `/docs-style-check-human` | Removes AI writing patterns (em dashes, filler phrases, uniform sentences) | It alters literal content such as commands, key names, or code samples | +| 3d | `/docs-readability-check` | Estimates reading grade level, finds dense sentence patterns, and rewrites them to the target level for the doc type | It rewrites sentences without ever stating a grade level estimate | +| 3e | `/docs-grammar-spelling` | Grammar, spelling, and domain terminology check | A term is changed to something that isn't in your `glossary.yaml` | + +Two notes: + +- **Skipped stages:** I left out split (2), overview (2b), and everything from 4a onward, including publish and verify. +- **Argument for the style stages:** The README's examples show `/docs-diataxis-audit` taking a file path and `/docs-style-check-human` taking a directory (`docs/output/docs/`). It doesn't say how a doc reaches the output folder when you skip the split. Before running 3a, check what path each skill expects. + +For every stage, a general sign of trouble is that it leaves no commit. The README says each stage commits its output so changes can be traced to the stage that made them. + +## Knowledge files to fill in first + +Each has fill-in instructions at the top, and the README says to fill them in before creating a workspace: + +- `_knowledge/glossary.yaml`: your terminology, canonical forms, and common mistakes. This is what the grammar and terminology stages rely on. +- `_knowledge/style-guides/general/style-guide_general.md`: your voice, tone, and formatting rules. This is what the voice stage applies. +- `_knowledge/product-kb/`: your product model (endpoints, domain objects, error codes, and so on). The README ties it to Stage 4c, which isn't in this trial. It ships as a made-up "Acme Orders API", and Stage 0 copies it into the workspace either way, so replace it if you want the workspace to hold only your own material. + +The README's Configuration placeholders (`{YOUR_ORG}`, `{YOUR_DOCS_REPO}`, and so on) have names that point at publishing. The README doesn't say which skills contain them, so search the five trial skills for `{YOUR_` before running them. + +## How you'll know the trial worked + +The README doesn't define success, so these criteria are mine, built from what it promises: + +1. Every stage ran in order and produced what the README says it should (the audit's report and JSON, and the other stages' described edits or checks). +2. Each stage left its own commit, so you can open the history and tie every change to one stage. +3. You read each stage's diff and could accept or reject its changes. The gates only mean something if you actually used them. +4. Nothing outside your document changed, and no stage touched literal commands or key names. +5. Knowledge files drove the result: a terminology or style change traces back to a rule you wrote, not one inherited from the Acme starters. + +The README says it can vouch only for how the pipeline behaved on the author's docs, not yours. This trial is your evidence on that point. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-review-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/README-review-haiku.md new file mode 100644 index 0000000..2404a35 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-review-haiku.md @@ -0,0 +1,68 @@ +# README-review on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline". Below is a description of my own documentation setup. + +My docs are markdown files in a GitHub repository called acme-docs. A static site generator publishes them to docs.acme.example. I track work in Jira. One senior writer reviews every change. I use Claude Code. + +Using only the README, tell me: +1. Which stages I can use as they are. +2. Which stages I would have to adapt, and what I would change. +3. Which stages I should skip, and why. +4. Every placeholder in the README's Configuration table, with the value from my setup that should replace it. If my description does not give a value, write "not in my description" instead of guessing. + +A good answer covers all four points, uses the README's own stage names, and never invents a value for a placeholder. +``` + +Answer: + +## 1. Stages you can use as they are + +All stages 1–5 and most of stage 4 are pure text-analysis stages that don't depend on your specific repository structure: + +- Stage 1: diataxis-audit +- Stage 2: diataxis-split +- Stage 2b: diataxis-create-overview +- Stage 3a: style-check-structure +- Stage 3b: style-check-voice +- Stage 3c: style-check-human +- Stage 3d: readability-check +- Stage 3e: grammar-spelling +- Stage 4a: visuals-review +- Stage 4b: links-review +- Stage 4c: sme-review +- Stage 4d: changes-list +- Stage 5: decision-checkpoint + +You'll need to customize the knowledge files (glossary, product KB, style guide) for accuracy, but the stage logic itself works without modification. + +## 2. Stages that need adaptation + +- **Stage 0 (workspace-setup)**: Needs configuration (filling in placeholders), but no code changes. + +- **Stage 6 (publish)**: Needs adaptation for your docs pipeline. The stage "copies output to docs repo, adds frontmatter, creates branch + PR." You must verify: + - What frontmatter format your static site generator expects + - Whether the branch naming and PR creation logic match your GitHub workflow for acme-docs + - How commit messages should be constructed + +- **Post stage (verify)**: Needs adaptation to your deployment process. The stage "verifies the PR merged and changes are live." You need to adapt how it checks docs.acme.example—whether it waits for a deploy trigger, polls the site, or uses another verification method specific to your static site generator. + +## 3. Stages to skip + +The README states "any step that needs them is skipped" if you leave the optional placeholders `{SHARED_CONFIG_DIR}` and `{NOTES_DIR}` unset. However, **the README does not list which specific stages require these optional placeholders**, so you cannot determine from the README alone which stages to skip. You would need to read the individual skill files. + +## 4. Configuration placeholders + +| Placeholder | Value | +|---|---| +| `{YOUR_ORG}` | not in my description | +| `{YOUR_DOCS_REPO}` | acme-docs | +| `{YOUR_DOCS_SITE}` | docs.acme.example | +| `{YOUR_ISSUE_TRACKER}` | not in my description | +| `{YOUR_TICKET_URL}` | not in my description | +| `{YOUR_USERNAME}` | not in my description | +| `{YOUR_DOCS_REPO_PATH}` | not in my description | +| `{YOUR_DEFAULT_OG_IMAGE_URL}` | not in my description | + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-review-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/README-review-sonnet.md new file mode 100644 index 0000000..e718db7 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-review-sonnet.md @@ -0,0 +1,70 @@ +# README-review on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline". Below is a description of my own documentation setup. + +My docs are markdown files in a GitHub repository called acme-docs. A static site generator publishes them to docs.acme.example. I track work in Jira. One senior writer reviews every change. I use Claude Code. + +Using only the README, tell me: +1. Which stages I can use as they are. +2. Which stages I would have to adapt, and what I would change. +3. Which stages I should skip, and why. +4. Every placeholder in the README's Configuration table, with the value from my setup that should replace it. If my description does not give a value, write "not in my description" instead of guessing. + +A good answer covers all four points, uses the README's own stage names, and never invents a value for a placeholder. +``` + +Answer: + +# docs-pipeline fit for acme-docs + +## 1. Stages you can use as they are + +These don't depend on your platform, only on the knowledge files and placeholders being filled in: + +- **Orchestrator** (`/docs-pipeline`). Its example ticket `TICKET-1319` is the same shape as a Jira key. +- **Stage 0**, `/docs-workspace-setup` +- **Stage 1**, `/docs-diataxis-audit` +- **Stage 2**, `/docs-diataxis-split` +- **Stage 3a-3e**, the structure, voice, human, readability and grammar checks +- **Stage 4a**, `/docs-visuals-review`. Mermaid-first, which fits markdown files, though the README doesn't say whether your site generator renders Mermaid. +- **Stage 4b**, `/docs-links-review` +- **Stage 4c**, `/docs-sme-review` +- **Stage 4d**, `/docs-changes-list` +- **Stage 5**, `/docs-decision-checkpoint` + +Before 3b, 3e and 4c are trustworthy, replace the starter `_knowledge/` files (style guide, glossary, product KB). The README says the product KB describes a made-up "Acme Orders API". + +## 2. Stages to adapt + +- **Stage 6, `/docs-publish`.** + - It copies output to the docs repo, adds frontmatter, and creates a branch and PR. That matches a GitHub-hosted markdown repo. + - Check that the frontmatter it adds matches what your static site generator expects. The README doesn't list the fields, so read the skill file. + - Check how it names branches (`{YOUR_USERNAME}`) and links tickets, so Jira keys and URLs come out right. + - Check whether the PR is assigned to your senior writer. The README doesn't say. +- **Post stage, `/docs-work-verify`.** It verifies the PR merged and the changes are live. Point its "live" check at docs.acme.example. Your description doesn't say whether the generator deploys on merge, so confirm that. +- **Stage 5, the decision checkpoint.** The README says a person decides apply, skip or defer. Your description doesn't say who that is, so decide whether it is you, with the senior writer reviewing the PR, or the senior writer at this stage. + +## 3. Stages to skip + +Nothing in your description requires skipping a stage. Two are conditional: + +- **Stage 2 (split) and Stage 2b (`/docs-diataxis-create-overview`).** Skip them for a change whose audit shows a single doc type. 2b exists only to create an overview after a split. + +## 4. Configuration table placeholders + +| Placeholder | Value from your setup | +|---|---| +| `{YOUR_ORG}` | not in my description | +| `{YOUR_DOCS_REPO}` | `acme-docs` | +| `{YOUR_DOCS_SITE}` | `docs.acme.example` | +| `{YOUR_ISSUE_TRACKER}` | not in my description (the tool is Jira, but no URL base is given) | +| `{YOUR_TICKET_URL}` | not in my description | +| `{YOUR_USERNAME}` | not in my description | +| `{YOUR_DOCS_REPO_PATH}` | not in my description | +| `{YOUR_DEFAULT_OG_IMAGE_URL}` | not in my description | + +Three placeholders sit outside the table. `{SHARED_CONFIG_DIR}` and `{NOTES_DIR}` are optional, and any step that needs them is skipped if you leave them. `{YOUR_PIPELINE_DIR}` is filled in by the SETUP.md install loop. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-teach-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/README-teach-haiku.md new file mode 100644 index 0000000..cd7be8c --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-teach-haiku.md @@ -0,0 +1,60 @@ +# README-teach on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline", a set of Claude Code skills that improve documentation in fixed stages. Teach it to me as if I am a technical writer who has never used it. + +1. In plain language, say what problem it solves and what it does not do. +2. List the stages in order, one line each, and explain why the style passes come before the reviews. +3. Say exactly what the person does between every two stages, and what the AI does alone inside a stage. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead (so it never says the person does not touch a stage), and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README. +``` + +Answer: + +## What docs-pipeline does and does not do + +**The problem it solves:** You have a documentation draft. You need it reviewed and improved in a reliable order before it goes live. Docs-pipeline automates that workflow. It works through seven stages—from classifying your content, to fixing style and grammar, to checking for accuracy—and gates each step: nothing moves forward until you say it's ready. This prevents reviewers from wasting time on prose that still needs basic grammar fixes, and makes sure every suggestion gets an explicit decision before publishing. + +**What it does not do:** It does not train custom models or build machine-learning pipelines. It does not handle retrieval systems. The author used this on real documentation and can vouch for how it behaved on *their* docs, not on yours. You fill in placeholders and your own knowledge files (glossary, product info, style guide) before it fits your setup. It assumes your docs live in a git repo; if you use a different publish platform, you'd need to adapt the publish and verify stages. It does not claim production ML experience. + +## The stages in order + +| | | +|---|---| +| **Stage 0** | Workspace setup — creates directories and copies knowledge files | +| **Stage 1** | Audit — classifies content by Diataxis type (how-to, explanation, reference, tutorial) | +| **Stage 2** | Split — extracts content into separate typed files | +| **Stage 2b** | Create overview — writes an index entry-point after split | +| **Stage 3a** | Structure check — verifies required sections and headings | +| **Stage 3b** | Voice check — applies your style guide (tone, terminology, list formatting) | +| **Stage 3c** | Human check — removes AI writing patterns (em dashes, filler, uniform sentences) | +| **Stage 3d** | Readability check — estimates grade level, rewrites dense sentences to target level | +| **Stage 3e** | Grammar check — spelling, grammar, and domain terminology | +| **Stage 4a** | Visuals review — recommends diagrams and visual aids | +| **Stage 4b** | Links review — finds cross-link candidates across your docs | +| **Stage 4c** | SME review — checks accuracy, reader journey, naming, technical clarity | +| **Stage 4d** | Changes list — summarizes everything done | +| **Stage 5** | Decision checkpoint — walks through every recommendation to apply/skip/defer | +| **Stage 6** | Publish — copies output to repo, creates branch and PR | +| **Post** | Verify — confirms PR merged and changes are live | + +**Why style passes (3a–3e) come before reviews (4a–4c):** Style stages run first because reviewers should never read prose that still needs cleaning. Once the structure, voice, readability, and grammar are fixed, the SME reviewer can focus on accuracy and content, not on sentences that need rewriting. As the README says: "Style passes run before reviews, so the reviewers never read prose that still needs cleaning." + +## What the person does between stages vs. what the AI does alone + +**Between every two stages, you decide whether to proceed.** The README states: "Nothing moves to the next stage until a person says so." You review the output from the stage that just finished, and if it's ready, you give the go-ahead to move forward. If it needs fixes, you stop and adjust. Nothing happens automatically. + +**Inside each stage, the AI works alone.** The AI classifies content, splits files apart, checks structure and voice, rewrites for readability, marks grammar issues, suggests diagrams and links, and flags accuracy problems. Each stage's AI does one job and commits its output so the change can be traced back to that stage. + +**At the very end (Stage 5):** Before anything publishes, every recommendation—from every stage—gets an explicit decision from you: apply it, skip it, or defer it. The README says: "Before anything is published, every open recommendation gets an explicit apply, skip, or defer decision." This is where your final judgment comes in. + +--- + +Now let me check that you understand. **First question:** + +Can you name the stage that comes right after the "Create overview" stage and tell me what it checks? + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README-teach-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/README-teach-sonnet.md new file mode 100644 index 0000000..68c566f --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README-teach-sonnet.md @@ -0,0 +1,72 @@ +# README-teach on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-pipeline", a set of Claude Code skills that improve documentation in fixed stages. Teach it to me as if I am a technical writer who has never used it. + +1. In plain language, say what problem it solves and what it does not do. +2. List the stages in order, one line each, and explain why the style passes come before the reviews. +3. Say exactly what the person does between every two stages, and what the AI does alone inside a stage. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names every stage in order, names the readability check as Stage 3d and grammar as Stage 3e, explains that nothing moves forward without a person's go-ahead (so it never says the person does not touch a stage), and repeats the limits the README states. It must not invent a stage, a command, or a file that is not in the README. +``` + +Answer: + +# docs-pipeline, taught for a technical writer + +## 1. The problem it solves, and its limits + +**The problem.** Taking a documentation change from rough draft to published pull request involves many separate jobs: deciding what kind of content you have, fixing structure and voice, checking readability and grammar, adding diagrams and links, and checking accuracy. Done all at once, they blur together and it's hard to tell what changed or why. docs-pipeline is a chain of Claude Code skills. Each skill does one job, in a fixed order, and commits its output so every change traces back to the stage that made it. + +**What it does not do or claim:** +- It is prompts, ordering, and checks. There is no model training, no machine-learning pipeline, no retrieval system, and no claim of production ML experience. +- It does not move on by itself. Nothing advances until a person says so. +- It does not publish with open questions. Every open recommendation gets an explicit apply, skip, or defer decision first. +- It is a generic export. You must fill in the placeholders and the knowledge files before it fits your docs. The bundled product knowledge describes a made-up product (the "Acme Orders API"), so replace it before trusting Stage 4c. +- The publish and verify stages assume a git-based docs repo. +- The author vouches only for how it behaved on their own docs, not on yours. + +## 2. The stages, in order + +| Stage | Command | One line | +|---|---|---| +| 0 | `/docs-workspace-setup` | Creates the workspace, copies in the knowledge files, writes starter files | +| 1 | `/docs-diataxis-audit` | Classifies content by Diataxis type; produces an audit report and JSON mapping | +| 2 | `/docs-diataxis-split` | Extracts mixed content into typed files (how-to, explanation, reference, tutorial) | +| 2b | `/docs-diataxis-create-overview` | Creates the overview/index entry-point doc after a split | +| 3a | `/docs-style-check-structure` | Checks required sections, headings, and Diataxis structural rules | +| 3b | `/docs-style-check-voice` | Applies voice, tone, list formatting, and terminology rules | +| 3c | `/docs-style-check-human` | Removes AI writing patterns (em dashes, filler, uniform sentences) | +| 3d | `/docs-readability-check` | Estimates reading grade level, finds dense sentences, rewrites to the target level for the doc type | +| 3e | `/docs-grammar-spelling` | Grammar, spelling, and domain terminology check | +| 4a | `/docs-visuals-review` | Recommends diagrams and visual aids, Mermaid-first | +| 4b | `/docs-links-review` | Finds cross-link candidates across the docs corpus | +| 4c | `/docs-sme-review` | Domain accuracy, reader journey, naming collisions, technical clarity | +| 4d | `/docs-changes-list` | Generates `editorial-changes.md` summarizing everything done | +| 5 | `/docs-decision-checkpoint` | Walks through every open recommendation: apply / skip / defer | +| 6 | `/docs-publish` | Copies output to the docs repo, adds frontmatter, creates branch and PR | +| Post | `/docs-work-verify` | Verifies the PR merged and the changes are live | + +`/docs-pipeline` is the orchestrator that runs all of this stage by stage. + +**Why style passes (3a to 3e) come before reviews (4a to 4c).** So the reviewers never read prose that still needs cleaning. A reviewer judging accuracy or links shouldn't spend effort on clumsy structure, AI-sounding filler, or typos. + +## 3. Who does what + +**Between every two stages, the person gives the go-ahead.** That is the one thing the README states for every transition: nothing moves to the next stage until a person says so. The README doesn't describe in more detail what you do at each gap. Reading the stage's committed output before approving is the natural use of that gate, but that part is my inference, not README text. + +Other human actions the README does specify: +- **Before the first run:** install the skills (SETUP.md), fill in the placeholders and the three knowledge sources (glossary, product KB, style guide). Do this before Stage 0, because Stage 0 copies `_knowledge/` into each new workspace. +- **At Stage 5:** you decide apply, skip, or defer on every open recommendation. This is the main human decision, and it comes last, before publishing. + +**Alone inside a stage, the AI does that stage's one job** (the table above), then commits its output. You are not editing inside a stage. Stage 5 is the exception: it is the AI walking you through items so you can decide. Stages 6 and Post are also AI work (branch, PR, verification), but only after your Stage 5 decisions. + +## 4. Check your understanding + +**Question 1 of 3.** Stage 3c removes AI writing patterns, and 3d and 3e come right after it. Using the README's reasoning, why does the pipeline run all of 3a to 3e before the Stage 4 reviews, and what would go wrong for a reviewer if the order were reversed? + +Answer in your own words and I'll correct anything that's off before asking the next one. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/README.md b/pipelines/docs-pipeline/tests/prompt-runs/README.md new file mode 100644 index 0000000..8387a79 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/README.md @@ -0,0 +1,32 @@ +# Saved prompt runs + +These are the answers behind the "How these prompts were checked" paragraphs in the docs-pipeline README, the SETUP guide, and the readability skill README. + +**How they were produced.** On 2026-10-01 each prompt was run through the Claude Code command line (`claude -p`, version 2.1.287) with no tools and no other instructions, once on `sonnet` and once on `haiku`. The document the prompt names (plus `_knowledge/glossary.yaml` for the glossary prompt) was pasted after the prompt, and each bracketed input was replaced with a made-up sample. Each saved file shows the exact prompt that was sent, then the answer. + +**How they were graded.** The agent that ran them (Claude Sonnet 5.5, working under my direction) read each answer against that prompt's own "good answer" list. One run per prompt per model, so a Pass here says "this run met the list", not "this prompt always does". The maintainer has not re-read every answer. + +File names: `README-*` is the docs-pipeline README, `SETUP-*` is `SETUP.md`, `RC-*` is the README of `skills/docs-readability-check`. The ARCHITECTURE prompts and the prompts at the end of the style guides were checked on 2026-10-01 before this folder existed, and no records of those runs were kept. + +| Prompt | Sonnet | Haiku | +|---|---|---| +| README, understand and teach | Pass | Pass. It said the pipeline "works through seven stages", which counts the numbered stage groups and is not a figure the README states. | +| README, review against your own setup | Pass | Pass. It did not list the three optional placeholders, which the README describes in prose and not in the table. | +| README, adapt and test | Pass | Pass | +| SETUP, glossary | Pass (8 entries, because the sample text supports no more) | Pass | +| SETUP, understand and teach | Pass | Pass. It told me to replace every placeholder before the smoke test, although section 4 says the smoke test needs none. | +| SETUP, review against your own setup | Pass | Pass | +| SETUP, adapt and test | Pass | Pass on the third version of the prompt (see below) | +| Readability README, understand and teach | Pass | Pass on the second version of the prompt (see below) | +| Readability README, review against your own setup | Pass | Pass. It said all three of the sample's doc types match, where "conceptual pages" only loosely matches the README's "explanation". | +| Readability README, adapt and test | Pass | Pass. It suggested `webhook-retries-trial.md` as a name for the copy, which is an example and not a path from the README. | + +## Prompts that failed first and were changed + +The earlier versions that were kept are in `earlier-versions/`. + +- **Readability README, understand and teach, Haiku (v1).** The prompt asked for what the skill checks and changes. Haiku never stated the target grade for any doc type, then asked a quiz question that said the answer was in what it had just told me, which it was not. The prompt now asks for the target grade for each doc type. +- **SETUP, adapt and test, Haiku (v1, kept).** Haiku predicted what Stage 4c would report for the reader's own doc, which the guide does not say. The prompt now says "Do not predict what any stage will find in my doc". +- **SETUP, adapt and test, Haiku (v2, not kept).** The answer to the second version of the prompt kept `sample/` in the copy command, so the command pointed at a folder that does not exist for the reader's own doc. That file was overwritten by the next run and I did not keep it. The prompt now asks for the doc's location to be written as ``. The third version passed on Haiku and Sonnet. + +The first version of the SETUP "adapt and test" prompt (before the guide had a smoke test) failed on Haiku in an earlier check. That is why this prompt now adapts the guide's own smoke test instead of asking the model to write one from nothing. diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-haiku.md new file mode 100644 index 0000000..44be9dd --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-haiku.md @@ -0,0 +1,33 @@ +# SETUP-adapt on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Section 4 is a smoke test on a sample doc. I want to run the same test on one of my own short docs instead. + +reset-api-key.md. It explains how to reset an API key from the dashboard. + +Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. In the copy command, write my doc's location as ``. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. Do not predict what any stage will find in my doc. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly. + +A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them. +``` + +Answer: + +## Smoke test for reset-api-key.md + +This runs the pipeline on your doc (`reset-api-key.md`, explaining how to reset an API key from the dashboard). It stops before anything is published and needs no placeholders. Run these in Claude Code: + +1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. +2. In that folder, copy your doc in: `cp "/reset-api-key.md" docs/output/docs/` +3. `/docs-style-check-voice docs/output/docs/` (Stage 3b). It edits your doc in place and writes a report to `docs/output/_process/style-audit/`. +4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `_process/sme-review/reset-api-key-sme-review.md`. + +**What proves it worked.** Stage 3b does not stop with "Style guide not found". Stage 4c does not stop with "Product KB not found". + +**About the Stage 4c findings.** Stage 4c checks your doc against the knowledge files in `_knowledge/product-kb/`, which currently describe a made-up product (the Acme Orders API). Until you replace them with your actual product's specifications, the SME review will compare your doc against that fictional product model. + +**Placeholders you do not need.** None. The smoke test needs zero placeholders from section 2. + +**Undo.** Delete the folder `~/projects/workspace_doc-1_smoke-test/`. Nothing else was changed. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-sonnet.md new file mode 100644 index 0000000..4fc451f --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-adapt-sonnet.md @@ -0,0 +1,41 @@ +# SETUP-adapt on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Section 4 is a smoke test on a sample doc. I want to run the same test on one of my own short docs instead. + +reset-api-key.md. It explains how to reset an API key from the dashboard. + +Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. In the copy command, write my doc's location as ``. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. Do not predict what any stage will find in my doc. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly. + +A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them. +``` + +Answer: + +## Smoke test for `reset-api-key.md` + +Run these in Claude Code, in this order: + +1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. +2. In that folder, copy your doc in: `cp "" docs/output/docs/` +3. `/docs-style-check-voice docs/output/docs/` (Stage 3b). It edits `reset-api-key.md` in place and writes a report to `docs/output/_process/style-audit/`. +4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `_process/sme-review/reset-api-key-sme-review.md`. + +The test stops after Stage 4c. Nothing is published. + +**What proves it worked.** Stage 3b does not stop with "Style guide not found". Stage 4c does not stop with "Product KB not found". Both stages finish and write their reports to the paths above. The guide's other expected results (a tone fix from a casual opener, and the three HIGH findings about cancellations, webhooks and the rate limit) apply only to the sample doc, so I have left them out. They say nothing about what your doc will produce. + +**Undo.** Delete the folder `~/projects/workspace_doc-1_smoke-test/`. Nothing else was changed. + +## Placeholders in section 2 + +You do not need to fill in any of them for this test. That covers all eight `{YOUR_...}` placeholders (`{YOUR_ORG}`, `{YOUR_DOCS_REPO}`, `{YOUR_DOCS_SITE}`, `{YOUR_DOCS_REPO_PATH}`, `{YOUR_ISSUE_TRACKER}`, `{YOUR_TICKET_URL}`, `{YOUR_USERNAME}`, `{YOUR_DEFAULT_OG_IMAGE_URL}`). The three optional ones (`{SHARED_CONFIG_DIR}`, `{NOTES_DIR}`, `{YOUR_PIPELINE_DIR}`) can stay as they are. The install loop in section 3 fills in `{YOUR_PIPELINE_DIR}` itself, so the skills must be installed before you start. + +## Limit of this test + +Stage 4c cannot meaningfully check your doc yet. It compares your doc against `_knowledge/product-kb/`, which describes a made-up product (the "Acme Orders API"). Unless `reset-api-key.md` is about that product, the review will only show that the stage runs, not whether your doc is accurate. To get a real accuracy check, replace the knowledge files with your own, as described in section 5.2, before you create the workspace. A workspace keeps the copy of `_knowledge/` it was created with. + +Stage 3b is less affected. It uses the generic style guide, so it can run on your doc as it is. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-haiku.md new file mode 100644 index 0000000..4b92b96 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-haiku.md @@ -0,0 +1,106 @@ +# SETUP-glossary on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline" and its placeholder file `_knowledge/glossary.yaml`. Below is some text from my own documentation. + +An order draft is a saved order that has not been submitted yet. When a customer submits it, the draft becomes an order and an invoice is generated. Use the Ledger view to see every invoice. Webhook events for drafts are sent to the sandbox endpoint first. + +Following section 5.1 of the guide and the structure in the placeholder file, draft a first `glossary.yaml` with the 10 most important terms from my text. For every entry give the canonical form, the aliases only if my text shows them, and the docs_facing flag. Where my text does not show a capitalization rule or a common mistake, leave that field out and write "needs review" instead of inventing one. Do not infer a capitalization rule from how a word happens to be capitalized in my text. + +A good answer uses the field names from the placeholder file exactly, has no more than 10 entries, and marks everything it could not know as "needs review". +``` + +Answer: + +I'll draft a glossary.yaml following section 5.1 and the placeholder structure. Let me extract the 10 most important product-specific terms from your text. + +```yaml +# Domain Glossary +# Used by: docs-grammar-spelling +# +# Structure: +# +# - canonical: ExactTermHere +# docs_facing: true # false = internal-only; flag if found in customer docs +# aliases: +# - alternate spelling +# - abbreviation +# usage: +# capitalization: | +# Describe when to capitalize, abbreviate, or use code formatting. +# mistakes: +# - "wrong form" → "correct form": explanation +# +# Add one entry per term. Keep alphabetical. + +terms: + + - canonical: customer + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: draft + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: endpoint + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: invoice + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: Ledger + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: order + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: order draft + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: sandbox + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: sandbox endpoint + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: webhook event + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review +``` + +**Notes:** +- All 10 entries are docs-facing; your text shows them in customer-visible documentation. +- No aliases appear in your text (e.g., you don't show "order-draft" or "Order Draft"), so none are listed. +- All capitalization and mistake entries marked "needs review" because your text doesn't show explicit rules or common pitfalls—only single instances. ("Ledger" appears capitalized once, but that's not enough to infer a rule.) +- Alphabetical order maintained as specified. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-sonnet.md new file mode 100644 index 0000000..a4afad7 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-glossary-sonnet.md @@ -0,0 +1,79 @@ +# SETUP-glossary on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline" and its placeholder file `_knowledge/glossary.yaml`. Below is some text from my own documentation. + +An order draft is a saved order that has not been submitted yet. When a customer submits it, the draft becomes an order and an invoice is generated. Use the Ledger view to see every invoice. Webhook events for drafts are sent to the sandbox endpoint first. + +Following section 5.1 of the guide and the structure in the placeholder file, draft a first `glossary.yaml` with the 10 most important terms from my text. For every entry give the canonical form, the aliases only if my text shows them, and the docs_facing flag. Where my text does not show a capitalization rule or a common mistake, leave that field out and write "needs review" instead of inventing one. Do not infer a capitalization rule from how a word happens to be capitalized in my text. + +A good answer uses the field names from the placeholder file exactly, has no more than 10 entries, and marks everything it could not know as "needs review". +``` + +Answer: + +Your text only supports 8 distinct terms, so this draft has 8 entries rather than padding to 10. + +```yaml +terms: + + - canonical: customer + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: invoice + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: Ledger view + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: order + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: order draft + docs_facing: true + aliases: + - draft + usage: + capitalization: needs review + mistakes: needs review + + - canonical: sandbox endpoint + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: submit + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review + + - canonical: webhook event + docs_facing: true + usage: + capitalization: needs review + mistakes: needs review +``` + +Things to check: + +- **Aliases:** Only `order draft` has one. Your text uses "draft" and "drafts" for it. I left `aliases` out everywhere else because the text shows no alternate forms. +- **`docs_facing: true`:** I set this on every entry because all of these terms appear in your documentation. Your text doesn't say whether any of them are internal-only, so confirm that. +- **Canonical forms:** These are copied from your text. `Ledger view` is capitalized there, but that is only how I found it. I did not treat it as a rule, so its capitalization is "needs review". `webhook event` is lowercase because the only occurrence is at the start of a sentence, which makes that form a guess to confirm. +- **Placeholder file:** `API`, `webhook` and `sandbox` are already in the starter file with their own rules. None of them come from your text, so I didn't copy them. You can keep them, or fold `sandbox endpoint` and `webhook event` into those entries. If you merge this draft in, keep the file alphabetical, as its header asks. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-haiku.md new file mode 100644 index 0000000..361cf3c --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-haiku.md @@ -0,0 +1,47 @@ +# SETUP-review on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Below is the output of the commands I ran on my machine. + +2.1.287 (Claude Code) +github.com + Logged in to github.com account example-user (keyring) + Active account: true +git version 2.45.1 +v22.3.0 +zsh: command not found: markdownlint + +Compare my output with the "Prerequisites" section. For each prerequisite, say whether it is met, missing, or impossible to tell from my output, and quote the line of my output that shows it. Then say what I must do before the first run. + +A good answer has one line per prerequisite, never marks something as met without a line of output to show it, and does not guess about anything my output does not cover. +``` + +Answer: + +Comparing your output to the Prerequisites section (section 1): + +| Prerequisite | Status | Evidence | +|---|---|---| +| Claude Code installed | **Met** | `2.1.287 (Claude Code)` | +| GitHub CLI (`gh`) installed and authenticated | **Met** | `Logged in to github.com account example-user (keyring)` and `Active account: true` | +| Git installed | **Met** | `git version 2.45.1` | +| Node.js with `markdownlint-cli` | **Missing** | `zsh: command not found: markdownlint` | +| A docs repository with markdown files | **Impossible to tell** | No output shown | +| A published docs site | **Impossible to tell** | No output shown | + +**What you must do before the first run:** + +Install `markdownlint-cli` globally: +```bash +npm install -g markdownlint-cli +``` + +Then verify it is available: +```bash +markdownlint --version +``` + +This is required by the `docs-publish` skill (Stage 6). You can run the smoke test in section 4 without it (it stops before publishing), but you will need it for any full pipeline run. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-sonnet.md new file mode 100644 index 0000000..fe49911 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-review-sonnet.md @@ -0,0 +1,44 @@ +# SETUP-review on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Below is the output of the commands I ran on my machine. + +2.1.287 (Claude Code) +github.com + Logged in to github.com account example-user (keyring) + Active account: true +git version 2.45.1 +v22.3.0 +zsh: command not found: markdownlint + +Compare my output with the "Prerequisites" section. For each prerequisite, say whether it is met, missing, or impossible to tell from my output, and quote the line of my output that shows it. Then say what I must do before the first run. + +A good answer has one line per prerequisite, never marks something as met without a line of output to show it, and does not guess about anything my output does not cover. +``` + +Answer: + +## Prerequisites check + +| Prerequisite | Status | Evidence | +|---|---|---| +| Claude Code available as `claude` | **Met** | `2.1.287 (Claude Code)` | +| GitHub CLI installed | **Met** | `Logged in to github.com account example-user (keyring)` | +| `gh` authenticated for the org that owns the docs repo | **Impossible to tell** | Your output shows a login (`Active account: true`) but not which org or repo that account can reach. | +| Git installed | **Met** | `git version 2.45.1` | +| Node.js installed | **Met** | `v22.3.0` | +| `markdownlint-cli` available | **Missing** | `zsh: command not found: markdownlint` | +| A docs repo with markdown files | **Impossible to tell** | None of the commands cover this. | +| A published docs site or staging environment | **Impossible to tell** | None of the commands cover this. | + +## What to do before the first run + +1. **Install markdownlint-cli:** `npm install -g markdownlint-cli`. Then re-run `markdownlint --version` to confirm. The guide says only `docs-publish` (Stage 6) needs it, so it doesn't block the smoke test, but you need it before a full pipeline run. +2. **Check `gh` access to the docs org.** Run `gh repo view {YOUR_ORG}/{YOUR_DOCS_REPO}` with your real names. If it fails, run `gh auth login` for the right account. Stages 4b, 4c (naming check) and 6 depend on this. +3. **Confirm you have a docs repo and a published or staging site.** Only you can check this. +4. **Install the skills (section 3).** Run the install loop, then confirm `/docs-` lists 17 skills. +5. **Run the smoke test (section 4).** It needs no placeholders and no markdownlint. +6. **Before running on real docs:** fill in the docs-repo placeholders from section 2 and replace the starter `_knowledge/` files from section 5 with your own. + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-haiku.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-haiku.md new file mode 100644 index 0000000..b1375cb --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-haiku.md @@ -0,0 +1,57 @@ +# SETUP-teach on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Teach it to me as if I am an engineer who has never used it. + +1. Turn the guide into a numbered checklist in the order I should do things, with one sentence on why each step exists. +2. Say which steps I can skip for a first trial and which I cannot. +3. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer follows the guide's order, covers the prerequisites, the placeholders, the install loop, the smoke test, the knowledge sources, and running the pipeline, and does not add a step the guide does not contain. +``` + +Answer: + +# The docs-pipeline Checklist + +Here's what to do in order: + +1. **Verify Claude Code is installed** — This is the tool that runs every stage of the pipeline +2. **Verify GitHub CLI is installed and authenticated to your org** — Needed to clone your docs repo and create PRs +3. **Verify Git is installed** — Required for version control throughout the pipeline +4. **Verify Node.js is installed with `markdownlint-cli` globally** — The publish stage needs this to validate markdown +5. **Ensure you have a docs repository with markdown files** — This is what the pipeline will improve +6. **Ensure you have a published docs site** — This is where improved docs are synced to +7. **Find and replace all `{YOUR_*}` placeholders in the guide's markdown files** — Each skill file references your org's specific values (repo name, domain, username) and won't work with placeholders +8. **Run the install loop from inside the pipeline folder** — This copies the 16 markdown skill files to Claude Code's skills directory and fills in your pipeline path on each copy +9. **Start a new Claude Code session and verify all 17 skills registered** — Type `/docs-` and confirm you see all 17 skill names listed; if you don't, the loop wrote to the wrong folder +10. **Run the smoke test on the included sample doc** — This validates that your setup works end-to-end without needing your real configuration +11. **Populate `_knowledge/glossary.yaml` with your product's 10–20 key terms** — Stage 3e (grammar) won't flag errors unless terms are in the glossary +12. **Populate all 7 files in `_knowledge/product-kb/`** — Stage 4c (SME review) fact-checks against these files and will stop if the KB is missing +13. **Customize `_knowledge/style-guides/general/style-guide_general.md` to match your team's conventions** — Stage 3b loads this; a baseline is already there, but you can add your own rules +14. **Run the full pipeline** — Once everything is set up, run `/docs-pipeline TICKET-ID slug` on your real docs + +--- + +## What you can skip for a first trial + +**Cannot skip:** Steps 1–9 (prerequisites and install) +You need all of these before anything will work. + +**Can skip:** Steps 11–12 (knowledge source population) +The smoke test (step 10) works with *sample* data that ships with the pipeline. You must populate these before running the pipeline on *real* docs, but for a first trial, you can run the smoke test and see the pipeline work without building the glossary and knowledge base. + +**Can skip:** Step 13 (customizing the style guide) +The baseline is already there and sufficient to run Stage 3b. Customize it only if your team has specific conventions beyond the defaults. + +**Can skip:** Step 14 (running on real docs) +The smoke test (step 10) is the trial; the full pipeline is the real work. + +--- + +Now I'll ask you three questions to check you understand. **Answer the first one before I ask the second.** + +**Question 1:** You're about to run the install loop in step 8. What does that loop do, and why can't you just copy the `.md` files manually? + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-sonnet.md b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-sonnet.md new file mode 100644 index 0000000..93e3927 --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/SETUP-teach-sonnet.md @@ -0,0 +1,56 @@ +# SETUP-teach on sonnet + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Teach it to me as if I am an engineer who has never used it. + +1. Turn the guide into a numbered checklist in the order I should do things, with one sentence on why each step exists. +2. Say which steps I can skip for a first trial and which I cannot. +3. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer follows the guide's order, covers the prerequisites, the placeholders, the install loop, the smoke test, the knowledge sources, and running the pipeline, and does not add a step the guide does not contain. +``` + +Answer: + +# docs-pipeline: checklist + +The guide has nine sections. Sections 1-6 are the things you do, in order. Sections 7-9 are reference material (which skill reads which file, when to refresh knowledge, and what to do about errors), so they aren't steps. + +## Checklist + +1. **Check the prerequisites (section 1).** You need Claude Code (`claude`), `gh` authenticated for your org, Git, Node with `markdownlint-cli`, a docs repo, and a published or staging docs site. Skills fail partway through if a tool is missing. +2. **Replace the placeholders (section 2).** Find and replace the `{YOUR_...}` values in all the `.md` files in the folder, for the stages you plan to use. The install step copies the files, so a change made afterward means a re-install. +3. **Check what's left with the grep one-liner (section 2).** `grep -rl '{YOUR_' . --include='*.md'` shows any placeholder you missed. `{YOUR_PIPELINE_DIR}` will still appear in the source files, and that is expected. +4. **Run the install loop (section 3).** Claude Code only loads skills from `//SKILL.md`, and the repo's files are flat. The loop builds the folders, fills in `{YOUR_PIPELINE_DIR}`, and adds `docs-readability-check` from the repo's `skills/` folder, for 17 skills in total. +5. **Confirm they registered (section 3).** Start a new session and type `/docs-`, or run the `claude -p ... | wc -l` command. You should see 17. If the count is lower, check `SKILLS_DIR` and open a fresh session. +6. **Run the smoke test (section 4).** + - Run `/docs-workspace-setup TICKET-1 smoke-test`, answer `y`, copy in the sample doc, then run `/docs-style-check-voice` and `/docs-sme-review`. + - It proves the skills load their knowledge files and produce the expected findings, without publishing anything. + - To undo it, delete `~/projects/workspace_doc-1_smoke-test/`. +7. **Build your knowledge sources (section 5).** Fill them in once, in the pipeline folder, before you create workspaces, because Stage 0 copies `_knowledge/` into each workspace and earlier workspaces keep the old copy. + - 7a. Glossary (`glossary.yaml`) is used by grammar (3e). + - 7b. Product knowledge base (`product-kb/`, seven files) is used by the SME review (4c). Refresh the `extracted:` date in `index.md`. + - 7c. Style guide (`style-guide_general.md`) is used by voice (3b). +8. **Run the pipeline on real docs (section 6).** Run `/docs-pipeline TICKET-ID slug`. It pauses between stages, and at each pause you say `proceed`, `skip`, `stop`, or `redo` and do the job in the section 6 table. Individual skills can also be run on their own. + +## What you can skip for a first trial + +| Step | First trial | Why | +|---|---|---| +| 1. Prerequisites | **Partly skippable** | The guide says the docs repo placeholders are needed only for links (4b), the naming-collision part of 4c, publish, and the post-merge check. So `gh`, `markdownlint`, and the docs site matter only for those stages. This is my reading, since the guide lists them all as "before running any skill". You still need Claude Code and your clone of this repo. | +| 2. Placeholders | **Skip** | The guide says the smoke test needs none of them. The three optional ones can stay as they are. | +| 3. Grep check | **Skip** | There is nothing to check if you filled in nothing. | +| 4. Install loop | **Cannot skip** | Without it, the skills don't exist for Claude Code. | +| 5. Registration check | **Cannot skip** | It is the quickest way to catch a wrong `SKILLS_DIR`. | +| 6. Smoke test | **Skippable, but I'd keep it** | It is the only check in the guide that the knowledge files load and the findings come out as expected. | +| 7. Knowledge sources | **Skip, and don't do it yet** | The starters ship working. The smoke test's expected findings depend on the made-up Acme KB, so replacing it first would change the results. You must do this before any real docs. | +| 8. Full pipeline | **Skip for the trial** | The smoke test replaces it. It is the real goal afterward. | + +**You cannot skip these before real docs:** the install loop, your own knowledge sources (the guide says to populate all three), and the placeholders for any stage you use. That includes the docs-repo ones for publish. + +## Question 1 of 3 + +In step 2 you replace placeholders, and in step 4 you run the install loop. Suppose you run the install loop first, then notice you forgot to set `{YOUR_ORG}` and fix it in the files in the pipeline folder. Will Claude Code see the change in your next session? Why or why not? + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/RC-teach-haiku-v1.md b/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/RC-teach-haiku-v1.md new file mode 100644 index 0000000..763b2fc --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/RC-teach-haiku-v1.md @@ -0,0 +1,47 @@ +# RC-teach on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the README for "docs-readability-check", a Claude Code skill that rewrites dense sentences in docs. Teach it to me as if I am a technical writer who has never used it. + +1. Say in plain language what it checks and what it changes. +2. Say what it never touches. +3. Say where its report goes. +4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. + +A good answer names the four sentence patterns, gives the target grade for each doc type, says tables, code blocks and callouts are never edited, and does not invent a feature or a command that is not in the README. +``` + +Answer: + +# What docs-readability-check does + +## 1. What it checks and what it changes + +The skill measures how hard your docs are to read by giving them a grade level (like "10th grade" or "college freshman"). It looks at a sample of 250 words from the middle of each doc and searches for four sentence patterns that make technical writing feel dense and heavy: + +- **Stacked clauses** — too many dependent clauses chained together +- **Too many facts in one sentence** — when one sentence tries to do the work of three +- **Jargon followed by explanation** — when you use a term and then pause to explain what it means +- **Wall paragraphs** — very long paragraphs with no breaks + +When it finds these patterns, it rewrites the sentences to be simpler and clearer — but it never changes your vocabulary, structure, or voice, and it never adds or removes information. + +## 2. What it never touches + +The skill **will not edit**: +- Tables +- Code blocks +- Callouts + +If it finds a paragraph it isn't confident about, it flags that paragraph for you to fix by hand instead of rewriting it. + +## 3. Where the report goes + +The skill writes a report to `_process/style-audit/readability-audit-{folder-name}.md` (relative to your project root). If your docs are inside an Obsidian vault, the report goes to `_system-audits/` in the vault instead. + +--- + +**Now, here's my first question:** The skill sets different target grade levels for different doc types. Which two doc types get the same target grade range? (You can find the answer in what I just told you.) + diff --git a/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/SETUP-adapt-haiku-v1.md b/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/SETUP-adapt-haiku-v1.md new file mode 100644 index 0000000..717327f --- /dev/null +++ b/pipelines/docs-pipeline/tests/prompt-runs/earlier-versions/SETUP-adapt-haiku-v1.md @@ -0,0 +1,35 @@ +# SETUP-adapt on haiku + +Prompt (inputs filled with made-up samples): + +```text +I have attached the setup guide for "docs-pipeline". Section 4 is a smoke test on a sample doc. I want to run the same test on one of my own short docs instead. + +reset-api-key.md. It explains how to reset an API key from the dashboard. + +Rewrite the smoke test in section 4 for my doc. Change only what has to change for my file. Keep every command the guide gives, in the guide's order. Say which placeholders in section 2 I still do not need to fill in for this test. Do not invent a command or a file path. If my doc cannot be checked the way section 4 describes (for example because it is not about a product the knowledge files describe), say so plainly instead of promising a result. + +A good answer keeps the guide's commands and order, changes only the file name and where the guide's expected results depend on the sample doc, stops before the publish stage, repeats the guide's undo step, and says that Stage 4c checks my doc against the knowledge files, which describe a made-up product until I replace them. +``` + +Answer: + +# Smoke test for reset-api-key.md + +Run these steps in Claude Code: + +1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. +2. In that folder, copy your doc in: `cp "/reset-api-key.md" docs/output/docs/` +3. `/docs-style-check-voice docs/output/docs/` (Stage 3b). It edits your doc in place and writes a report to `docs/output/_process/style-audit/`. +4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `_process/sme-review/reset-api-key-sme-review.md`. + +**What proves it worked.** Stage 3b does not stop with "Style guide not found". Stage 4c does not stop with "Product KB not found". + +Stage 4c will check your doc against `_knowledge/product-kb/`, which currently describes the made-up Acme Orders API product. Since your doc is about resetting an API key from the dashboard, its accuracy findings will compare your content against that fictional product model rather than your own product. The report will flag claims as unverified until you replace the knowledge files with your actual product information. + +**Undo.** Delete the folder `~/projects/workspace_doc-1_smoke-test/`. Nothing else was changed. + +--- + +**Placeholders you still do not need to fill in for this test:** All of them. Section 2 states "The smoke test in section 4 needs none of them." + diff --git a/skills/docs-readability-check/README.md b/skills/docs-readability-check/README.md index 7469716..7c8027b 100644 --- a/skills/docs-readability-check/README.md +++ b/skills/docs-readability-check/README.md @@ -53,7 +53,7 @@ Paste this into any AI model, together with this document and the files it descr ```text I have attached the README for "docs-readability-check", a Claude Code skill that rewrites dense sentences in docs. Teach it to me as if I am a technical writer who has never used it. -1. Say in plain language what it checks and what it changes. +1. Say in plain language what it checks and what it changes, and give the target grade for each doc type. 2. Say what it never touches. 3. Say where its report goes. 4. Then ask me three questions to check that I understood, one at a time. Wait for my answer before the next one, and correct me where I am wrong. @@ -88,4 +88,10 @@ Write me a trial plan. Use the install commands and the slash command from the R A good answer uses the README's install commands and the exact command `/docs-readability-check [folder-or-file]`, tells me to work on a copy because the skill edits in place, names the report folder the README gives, and does not promise a particular grade level for my doc. ``` -**How these prompts were checked.** PENDING_RUN_RECORD +**How these prompts were checked.** On 2026-10-01 I ran every prompt in this document through the Claude Code command line, once against Claude Sonnet and once against Claude Haiku (the `sonnet` and `haiku` model names in Claude Code 2.1.287). Each run was a fresh session with no tools and no other instructions. I attached this document, replaced each bracketed input with a made-up sample, and read every answer against that prompt's "good answer" list. One run per prompt per model: a Pass means that run met the list, not that the prompt always does. The answers are saved in [`pipelines/docs-pipeline/tests/prompt-runs/`](../../pipelines/docs-pipeline/tests/prompt-runs/README.md) (the files that start with `RC-`). I have not run them against models from other vendors, so "any AI model" means "should work", not "verified". + +| Prompt | Sonnet | Haiku | +| --- | --- | --- | +| Understand and teach | Pass | Pass after a fix. The first version asked only what the skill checks and changes, and Haiku never stated the target grade for any doc type, then asked a quiz question whose answer it had not given. The prompt now asks for the target grade for each doc type. | +| Review against your own setup | Pass | Pass. It said all three of my sample's doc types match, where "conceptual pages" only loosely matches the README's "explanation". | +| Adapt and test | Pass | Pass. It suggested a name for the copy that is an example, not a path from the README. | From 52a8ba3de095d0265a952aa6397ef0f16d9fdc64 Mon Sep 17 00:00:00 2001 From: darthrootbeer Date: Thu, 1 Oct 2026 22:42:53 -0400 Subject: [PATCH 4/5] docs(docs-pipeline): save smoke test run from a fresh clone Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01XV3Ggh86cf2xwUyz28XaN6 --- pipelines/docs-pipeline/SETUP.md | 2 +- .../docs-pipeline/tests/smoke-test-run.md | 237 ++++++++++++++++++ 2 files changed, 238 insertions(+), 1 deletion(-) create mode 100644 pipelines/docs-pipeline/tests/smoke-test-run.md diff --git a/pipelines/docs-pipeline/SETUP.md b/pipelines/docs-pipeline/SETUP.md index 54bf578..f8221cb 100644 --- a/pipelines/docs-pipeline/SETUP.md +++ b/pipelines/docs-pipeline/SETUP.md @@ -96,7 +96,7 @@ Then the real test. This runs the pipeline on a short sample doc that ships in t 1. `/docs-workspace-setup TICKET-1 smoke-test` and answer `y`. This creates `~/projects/workspace_doc-1_smoke-test/` with a copy of `_knowledge/`. 2. In that folder, copy the sample in: `cp "/sample/acme-orders-cancellations.md" docs/output/docs/` 3. `/docs-style-check-voice docs/output/docs/` (Stage 3b). It edits the sample in place and writes a report to `docs/output/_process/style-audit/`. -4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `_process/sme-review/acme-orders-cancellations-sme-review.md`. +4. `/docs-sme-review docs/output/docs/` (Stage 4c). It writes `acme-orders-cancellations-sme-review.md` and a summary into a `_process/sme-review/` folder (the model may place it under `docs/output/` or at the workspace root). **What proves it worked.** Stage 3b does not stop with "Style guide not found". The sample has a casual opener, so the voice report lists at least one tone fix. Stage 4c does not stop with "Product KB not found". Its report lists at least these three HIGH domain findings, because the sample contradicts `_knowledge/product-kb/`: a paid order cannot be canceled, the hosted order form does not receive webhooks, and the rate limit is 100 a minute, not a thousand. diff --git a/pipelines/docs-pipeline/tests/smoke-test-run.md b/pipelines/docs-pipeline/tests/smoke-test-run.md new file mode 100644 index 0000000..a64255f --- /dev/null +++ b/pipelines/docs-pipeline/tests/smoke-test-run.md @@ -0,0 +1,237 @@ +# Smoke test run, saved output + +This is the real output of following the Install and Smoke test sections of [SETUP.md](../SETUP.md) literally, from a fresh clone, on 2026-10-01 (Claude Code 2.1.287, `sonnet` for the stages). + +**What was run, and what was changed to keep it away from my own setup.** I cloned the pushed branch of this repo from GitHub into an empty temp folder, ran the check script, ran the install loop exactly as written but with `SKILLS_DIR` pointed at a scratch project folder instead of `~/.claude/skills`, and ran each stage with `claude -p`. Because the skills sit in a scratch folder and not in the user folder, each stage run adds `--add-dir ` so Claude Code can see them from inside the workspace, and `--setting-sources project` keeps my own user settings out. The install-count check uses the same flags. Before the run I also changed the `WORKSPACE_ROOT` line in the two installed copies that use it from `~/projects` to a scratch folder, which the guide says you can do. Nothing else was edited. + +## Part 1: the fresh clone, install, stage 0, stage 3b, stage 4c + +Commit under test: `e035975`. + +```text +$ git clone -b fix/docs-pipeline-runnable https://github.com/darthrootbeer/context-engineering-toolkit.git repo +commit e035975 docs(docs-pipeline): add saved prompt runs, offline check and readability skill readme + +$ python3 pipelines/docs-pipeline/tests/check_pipeline.py +check_pipeline: clean (17 skill files, 50 files scanned) +exit=0 + +$ install loop (SETUP.md section 3; SKILLS_DIR pointed at a scratch folder) +skill folders created: 17 + +$ claude -p "hi" --model haiku --output-format stream-json --verbose | grep -o "\"docs-[a-z-]*\"" | sort -u | wc -l + 17 + +$ claude -p "/docs-workspace-setup TICKET-1 smoke-test" (answering y) +The workspace is set up and the initial commit is made. + +``` +Done. + + /tmp/dpfix-proof3/proj/workspaces/workspace_doc-1_smoke-test/ + + Files: + - CLAUDE.md + - README.md + - .gitignore + + Knowledge files: + - _knowledge/ (copied from /tmp/dpfix-proof3/repo/pipelines/docs-pipeline) + + Directories: + - docs/input/ + - docs/output/_process/diataxis-audit/ + - docs/output/_process/link-check/ + - docs/output/_process/style-audit/ + - docs/output/_process/visual-audit/diagrams/ + - docs/output/docs/ +``` + +I skipped three optional steps because their settings are still placeholders: +- **Shared config link:** `SHARED_CONFIG_DIR` is unset, so there is no `_shared` link. +- **Project note:** `NOTES_DIR` is unset, so I wrote no project note. +- **Source doc fetch:** no docs repo is configured, so I didn't copy a source doc. Copy it into `docs/input/` manually. + +The ticket line in `CLAUDE.md` is the plain ID `TICKET-1`, with no link, because the ticket URL is also a placeholder. + +The first commit is `84c483e` on `master`. + +Next, copy the source doc into `docs/input/` and run `/docs-pipeline` or `/docs-diataxis-audit`. + +$ ls -A workspace; git log --oneline +_knowledge +.git +.gitignore +CLAUDE.md +docs +README.md +84c483e docs: scaffold guide workspace for TICKET-1 + +$ claude -p "/docs-style-check-voice docs/output/docs/" +General style audit complete. + +Docs audited: 1 +Fixes applied: 6 +Flags for review: 6 + +I fixed these in `acme-orders-cancellations.md`: +- I replaced the chatty, marketing intro with a direct opening. +- I split the long paragraph in "What a cancellation is" in two. +- I renamed the heading "How to cancel an order" to "Cancel an order". +- I added the `**To cancel an order:**` lead-in and an outcome sentence to the numbered list. +- I changed "order id" to the exact field name `order_id`. + +These are flagged for you to review: +- "Paid orders are refunded automatically" and "The API is rate limited" are passive. Check both claims against the product KB. +- "Hosted order form" and "integration type" are undefined at first use. +- "Things to know" mixes rate limits with the `reason` field. +- The doc has no closing "Prompt for your AI model" block. That belongs to the structural pass, so check it was handled there. + +Audit report: `docs/output/_process/style-audit/style-audit-general-docs.md` + +Committed as `1417607`. + +What's next: `/docs-style-check-human docs/output/docs/` for the AI pattern cleanup pass. + +$ claude -p "/docs-sme-review docs/output/docs/" +SME review complete. I committed the reports as `28d39b2`. + +- **Draft files analyzed:** 1 (`acme-orders-cancellations.md`) +- **Corpus titles indexed:** skipped, because no docs repo is configured, so the naming-collision check didn't run +- **Product KB extracted:** 2026-10-01. The KB is still the fictional starter data, so these findings only mean something once you've replaced it with your real product facts. + +**Reports** are in `docs/output/_process/sme-review/`. I put them there instead of a top-level `_process/` to match the other audit folders: +- `acme-orders-cancellations-sme-review.md` +- `sme-review-summary.md` + +**Findings (11 total):** +- **Domain accuracy:** 3 HIGH, 1 MEDIUM + - HIGH, line 13: the draft says paid orders can be canceled and are refunded automatically. The KB says a paid order can't be canceled (`order_not_cancelable`, 409). + - HIGH, line 37: the draft says every integration type gets `order.canceled`. Only Server API does, and the hosted order form gets no webhooks. + - HIGH, line 41: the draft gives a rate limit of about 1,000 requests a minute. The KB says 100 per API key. + - MEDIUM, line 20: the cancel endpoint is Server API only, and the page never says so. +- **Reader journey:** 3 MEDIUM + - There is no "who this is for" line or prerequisites. + - Only the 404 error is documented; the 409 and 429 errors are missing. + - The page doesn't say where to find `order_id`. +- **Naming collisions:** skipped +- **Technical clarity:** 1 MEDIUM, 3 LOW + - The MEDIUM is that the curl example sends JSON without a `Content-Type` header. + - The LOWs are an odd rationale sentence, a repeated outcome line and the word "Utilize". +- **Proofreading:** 0 + +Next is `/docs-changes-list`. I'd fix the three HIGH items first; the decision checkpoint at step 13 is where the apply/skip/defer choices get made. + +$ git log --oneline; find . -name "*.md" -path "*_process*" +28d39b2 docs: SME review pass for TICKET-1 +1417607 docs: general style voice pass for TICKET-1 +84c483e docs: scaffold guide workspace for TICKET-1 +./docs/output/_process/style-audit/style-audit-general-docs.md +./docs/output/_process/sme-review/sme-review-summary.md +./docs/output/_process/sme-review/acme-orders-cancellations-sme-review.md +``` + +**What this shows.** Stage 0 built a workspace with a copy of `_knowledge/`. Stage 3b loaded the style guide and wrote its report. Stage 4c loaded the product knowledge base and found the three HIGH domain errors the sample doc plants: a paid order cannot be canceled, the hosted order form gets no webhooks, and the rate limit is 100 a minute. Neither stage stopped on a missing file. The naming-collision check was skipped with a note, because no docs repo is configured. + +## Part 2: the other stages that need no docs repo + +These ran in the same kind of scratch workspace, one commit earlier (`6864bf7`, before the saved-run records and this file were added; no skill file, knowledge file or sample changed in between; only the README, SETUP, ARCHITECTURE and the readability README did). Stage 1 needed the sample copied into `docs/input/` first. + +**Stage 3a stopped on purpose.** `/docs-style-check-structure` needs a `diataxis_type` in the doc's frontmatter, and the split stage (not run here) is what adds it. Its message is a design rule, not a missing file. + +```text +$ claude -p "/docs-diataxis-audit docs/input/acme-orders-cancellations.md" +The audit is written and committed. I made no changes to the source file. + +- **Input:** `docs/input/acme-orders-cancellations.md` +- **Audit report:** `docs/output/_process/diataxis-audit/smoke-test_audit-report.md` +- **JSON mapping:** `docs/output/_process/diataxis-audit/smoke-test_mapping.json`. It passed the built-in ID, uniqueness and mapping checks before I wrote it. +- **SVG diagrams:** skipped, because no shared diagram tool is configured. +- **Sections analyzed:** 5. +- **Content type:** mixed, with no type above roughly 40%. Reference is the largest share (~40%), and how-to is the only step-by-step content. +- **Recommended split:** 3 typed documents, plus an overview that the split step creates. + - Explanation: how order cancellation works. + - How-to: cancel an order, with the `reason` tip moved in. + - Reference: webhooks, errors and rate limits. + +The main problems it flags: +- The "Things to know" section mixes a rate limit with a task tip. +- The 404 error sits inside the how-to steps. +- The promotional intro should be dropped. + +Three things to know: +- **Commits:** I committed the untracked source doc first (`444bce3`), then the audit (`2a9847a`). Your workflow says to commit after every step. +- **Earlier stages:** git history already shows voice-style and SME-review commits, and `docs/output/docs/acme-orders-cancellations.md` exists. That is later-stage work with no audit or split behind it. You may want to check whether it should be redone after the split. +- **SME check:** the audit flags two claims for review. One is that every integration type gets the webhook. The other is that paid orders are refunded automatically. + +Next is `/docs-diataxis-split`. + + +$ claude -p "/docs-style-check-structure docs/output/docs/" +I stopped before making any edits, because `docs/output/docs/acme-orders-cancellations.md` has no resolvable `diataxis_type`. + +- **Frontmatter:** the file has none. It starts with an HTML comment and then the `#` heading. +- **Filename:** `acme-orders-cancellations.md` matches none of the patterns (`index.md`, `*-overview.md`, `*-reference.md`, `how-to-*`, `tutorial-*`). + +``` +Cannot determine diataxis_type for: + - acme-orders-cancellations.md (no frontmatter type, no recognizable filename pattern) +``` + +**The split looks like it hasn't run.** The git log has the audit commit (`2a9847a`) as the latest. It has no split commit, and `docs/output/docs/` holds one file. That file reads like the original source: it mixes explanation ("What a cancellation is"), how-to steps, and webhook facts. There is also no `index.md` overview. Step 3 (`/docs-diataxis-split`) normally produces typed files with frontmatter, and running the structure check on the unsplit doc would give misleading results. + +Which would you like? + +1. **Run `/docs-diataxis-split` first (recommended).** That produces typed docs, and I then re-run this check. +2. **Let me assess and propose a type for this file now.** From the content I'd suggest `explanation`, but it's mixed content. You'd confirm before I add `diataxis_type` to the frontmatter and continue. + +I haven't written an audit report or made a commit. + + +$ claude -p "/docs-style-check-human docs/output/docs/" +Human style audit complete. + +Docs audited: 1 +Fixes applied: 4 +Flags for review: 1 + +Most common fixes: + - Passive voice: 2 + - Redundant sentence: 1 + - Short-sentence stacking: 1 + +The doc had almost no AI patterns. It has no em dashes, banned words, filler openers, or bold-label lists. + +The flag: "This helps with reporting" in "Things to know" doesn't say how it helps. Someone who knows the product should supply the specific benefit. + +Audit report: `docs/output/_process/style-audit/style-audit-human-docs.md` + +The changes are committed as `734ddc5`. + + +$ claude -p "/docs-readability-check docs/output/docs/" +Readability audit complete. + +- **Docs audited:** 1 (`acme-orders-cancellations.md`) +- **Docs improved:** 0 +- **Docs within target:** 1 +- **Docs still below target:** 0 +- **Wall paragraphs flagged for manual review:** 0 + +The doc reads at an easy level, about 8th–9th grade or below. That estimate is a rough hand calculation of the Flesch-Kincaid grade level (about 6–7). The doc has no `diataxis_type`, so the target is 11th–12th grade. Being easier than the target is fine for a short task guide. None of the seven dense-sentence patterns appeared, so I made no edits. + +The audit report is at `docs/output/_process/style-audit/readability-audit-docs.md`. I committed it as 48e8406. + + +$ claude -p "/docs-grammar-spelling docs/output/docs/" +Proofread audit complete. + +- **Docs audited:** 1 +- **Fixes applied:** 2, both punctuation. In `acme-orders-cancellations.md` I changed "order id" to `order_id` and "a 404 error" to a `404 Not Found` error. +- **Flags for review:** 1. Line 39 says "a thousand cancellation requests". That's a technical value, so it could be "1,000". I'd also confirm the limit against the rate-limit docs. +- **Terminology and spelling:** no issues. All glossary terms were in canonical form, and the spelling is American English. + +The audit report is at `docs/output/_process/style-audit/style-audit-proofread-docs.md`. I committed the changes as `f5c1678`. + +Next: review the flag, then run `/docs-visuals-review docs/output/docs/`. The workflow puts visuals review next, so I didn't suggest `/docs-links-review` yet. +``` From bba5bea866f9c9345ea96d3a247bc0d8df446550 Mon Sep 17 00:00:00 2001 From: darthrootbeer Date: Thu, 1 Oct 2026 22:45:18 -0400 Subject: [PATCH 5/5] ci: ignore one placeholder token in the docs-pipeline sample doc Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01XV3Ggh86cf2xwUyz28XaN6 --- .gitleaksignore | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .gitleaksignore diff --git a/.gitleaksignore b/.gitleaksignore new file mode 100644 index 0000000..a31d15e --- /dev/null +++ b/.gitleaksignore @@ -0,0 +1,3 @@ +# Placeholder token in a sample curl command (Authorization: Bearer YOUR_API_KEY), docs-pipeline sample doc. +# It is a fake value in a made-up example, not a credential. The line sits in an earlier commit of PR 30, which cannot be rewritten. +445b46ad65f98f2e34928eaf9340d5417edcde79:pipelines/docs-pipeline/sample/acme-orders-cancellations.md:curl-auth-header:22