Skip to content

Docs self-healing workflow improvements: Split into Haiku Router + Sonnet Drafter #3064

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pwizla merged 3 commits into from
Apr 16, 2026
+270 −101
Merged

Docs self-healing workflow improvements: Split into Haiku Router + Sonnet Drafter #3064

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9898c08
Split self-healing into 2-step Haiku Router + Sonnet Drafter
pwizla Apr 16, 2026
06dd782
Let Haiku handle micro-edits directly without invoking Sonnet
pwizla Apr 16, 2026
551519d
Raise rate limit from 1 to 5 PRs per run
pwizla Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 22 additions & 70 deletions .github/prompts/docs-self-healing.md → .github/prompts/docs-self-healing-drafter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,35 @@
# Strapi Documentation Self-Healing Agent
# Self-Healing Drafter (Sonnet)

You are running in automated mode inside a GitHub Actions workflow on `strapi/documentation`.
Your job is to process each PR merged into `strapi/strapi` in the last 24 hours and open a draft documentation PR on `strapi/documentation` for every one that requires a doc update.
The Router has already analyzed each PR and identified documentation targets.
Your job is to draft the content, create branches, and open draft PRs.

## Environment

- `$STRAPI_SOURCE` — local checkout of `strapi/strapi` (read-only, for diffs)
- `$DOC_REPO` — local checkout of `strapi/documentation` (read + write, for creating PRs)
- `$FILTERED_PRS` — JSON array of pre-filtered PRs (chores, CI, deps, tests already excluded by the workflow)
- `$DOC_REPO` — local checkout of `strapi/documentation` (read + write)
- `$ROUTER_RESULTS` — JSON with routing decisions from the Haiku Router step
- Pre-fetched diffs and bodies in `/tmp/pr-<NUMBER>-body.txt` and `/tmp/pr-<NUMBER>.diff`
- GitHub CLI (`gh`) is authenticated via `GH_TOKEN`
- Model: `claude-sonnet-4-6` (set in the workflow YAML; optimized for cost on batch automation)

## Step 1 — Read the pre-filtered PR list
## Step 1 — Parse Router results

The workflow has already fetched and filtered merged PRs. The list is in `$FILTERED_PRS` as a JSON array:
The Router results are in `$ROUTER_RESULTS` as a JSON string. Parse it.
Only process PRs where `decision` is `"has_targets"`. Skip the rest.

```json
[{"number": 12345, "title": "feat: add feature X", "html_url": "https://github.com/strapi/strapi/pull/12345"}, ...]
```

Parse this list. **Do NOT re-fetch PRs from the GitHub API** — the workflow already did that.

**Rate limit:** Process a maximum of 1 PR per run (testing mode). If more qualify, log the skipped ones
to stdout and they will be picked up on the next run.

## Step 2 — Read pre-fetched PR context (per PR)

The workflow has already fetched the body and diff for each PR. Read them from:

- `/tmp/pr-<NUMBER>-body.txt` — PR description
- `/tmp/pr-<NUMBER>.diff` — full diff

**Do NOT fetch these from the GitHub API** — they are already on disk.

**Diff size threshold:** If the diff exceeds 3000 lines, skip this PR and log:
"PR #<NUMBER> skipped — diff too large (X lines), flag for manual /autodoc".

## Step 3 — Run the Router (per PR)
Each PR with targets includes a `targets_yaml` field — this is the Router's full YAML output
containing `targets`, `doc_type`, `template`, `guide`, and `confidence`.

**Read these files once at the start of the run** (not per PR):
- Router prompt: `$DOC_REPO/agents/prompts/router.md`
- Sidebars: `$DOC_REPO/docusaurus/sidebars.js`
- Page index: `$DOC_REPO/docusaurus/static/llms.txt`
## Step 2 — Run the documentation pipeline (per PR with targets)

Then, for each PR, apply the Router logic using:
- PR title and description from Step 2
- The diff from Step 2

The Router will produce a YAML `targets` block.

**Skip the PR if:**
- The Router finds no targets
- The Router sets `ask_user` (log the question to stdout for manual handling)

Note: chores, CI, deps, tests, and translations are already filtered out by the workflow
before Claude runs. The Router only sees PRs that passed the pre-filter.

**If the Router finds no targets for ANY PR, skip Step 4 entirely.**
Do not load Drafter/checker prompts unless at least one PR has targets.

## Step 4 — Run the documentation pipeline (per PR with targets)

For each PR where the Router identified targets, run the Create/Update Mode pipeline.

**Load these agent prompts now** (not before — only if Step 3 found targets):
**Load these agent prompts now:**
- Orchestrator: `$DOC_REPO/agents/prompts/orchestrator.md`
- Outline Generator: `$DOC_REPO/agents/prompts/outline-generator.md`
- Drafter: `$DOC_REPO/agents/prompts/drafter.md`
- Style Checker: `$DOC_REPO/agents/prompts/style-checker.md`
- Integrity Checker: `$DOC_REPO/agents/prompts/integrity-checker.md`

For each PR, read the pre-fetched body and diff from `/tmp/pr-<NUMBER>-body.txt` and `/tmp/pr-<NUMBER>.diff`.

Follow the auto-chain execution from the Orchestrator:

1. **For `create_page` targets:**
Expand All @@ -93,13 +53,12 @@ Follow the auto-chain execution from the Orchestrator:
- Log any issues but do not block PR creation — Pierre will verify during review

**Authoring guides:** For each target, load the relevant authoring guide from `$DOC_REPO/agents/authoring/`
based on the Router's `doc_type` and target path. These contain section-specific conventions.
Authoring guides are small and target-specific — read them per target, not upfront.
based on the Router's `doc_type` and target path. Read per target, not upfront.

**Templates:** For `create_page` targets, load the relevant template from `$DOC_REPO/agents/templates/`
based on the Router's `doc_type`.

## Step 5 — Create branch and draft PR (per PR)
## Step 3 — Create branch and draft PR (per PR)

After the Drafter has produced output for all targets:

Expand All @@ -113,7 +72,6 @@ cd $DOC_REPO
BRANCH_NAME="<prefix>/<short-kebab-description>"

git checkout -b "$BRANCH_NAME"
# (apply all Drafter outputs to the appropriate files)
git add .
git commit -m "<DOCS_CHANGE_DESCRIPTION>
# Imperative mood, no prefix, describe the doc change. Max 80 chars."
Expand Down Expand Up @@ -146,36 +104,30 @@ git clean -fd
git reset --hard origin/main
```

## Step 6 — Write run summary
## Step 4 — Write run summary

After processing all PRs (or if none qualify), write a JSON summary to `/tmp/self-healing-summary.json`:
Write a JSON summary to `/tmp/self-healing-summary.json`:

```json
{
"processed": [
{"number": 12345, "title": "Add feature X", "doc_pr": "https://github.com/strapi/documentation/pull/99", "branch": "cms/add-feature-x"}
],
"skipped": [
{"number": 12346, "title": "Fix typo in test", "reason": "Router: no doc update needed"},
{"number": 12347, "title": "Massive refactor", "reason": "Diff too large (4200 lines)"}
],
"errors": [
{"number": 12348, "title": "Add plugin Y", "error": "Drafter failed after retry"}
]
}
```

**Always write this file**, even if all arrays are empty. The workflow reads it to build the job summary.
**Always write this file**, even if all arrays are empty.

## Rules

- **One draft PR per strapi/strapi PR** — never consolidate multiple PRs into one
- **Only modify files in `$DOC_REPO/docusaurus/docs/`** and `$DOC_REPO/docusaurus/static/` (for images)
- **Follow all conventions** in `$DOC_REPO/agents/` — the Router and authoring guides are the source of truth
- **Follow git-rules.md** — branch naming (`/cms`, `/cloud`, `/repo`), commit messages (imperative, no prefix), PR titles
- **If the Router sets `ask_user`:** skip this PR and log the question to stdout
- **If no PR requires a doc update:** exit cleanly without creating anything
- **Max 5 PRs per run** — log skipped PRs to stdout
- **If no PR has targets:** exit cleanly without creating anything
- **Max 3000 lines per diff** — skip and log oversized diffs
- **Never modify workflow files, configuration files, or sidebars.js**
- **NEVER run any write operation on strapi/strapi** — no issues, no comments, no PRs, no pushes, no API calls that modify state. The GH_TOKEN has write access but this workflow ONLY writes to strapi/documentation. Read-only access to strapi/strapi (diffs, PR bodies) is the only permitted use.
- **NEVER run any write operation on strapi/strapi** — no issues, no comments, no PRs, no pushes, no API calls that modify state. Read-only access to strapi/strapi (diffs, PR bodies) is the only permitted use.
135 changes: 135 additions & 0 deletions .github/prompts/docs-self-healing-router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Self-Healing Router (Haiku)

You are a lightweight routing agent. Your ONLY job is to decide, for each PR,
whether documentation needs updating and what targets to hit.

You run on Haiku for cost efficiency. Do NOT draft content or create PRs.

## Environment

- `$DOC_REPO` — local checkout of `strapi/documentation`
- `$FILTERED_PRS` — JSON array of pre-filtered PRs (chores/CI/deps/tests already excluded)
- Pre-fetched diffs and bodies in `/tmp/pr-<NUMBER>-body.txt` and `/tmp/pr-<NUMBER>.diff`

## Instructions

1. **Read these files once:**
- Router prompt: `$DOC_REPO/agents/prompts/router.md`
- Sidebars: `$DOC_REPO/docusaurus/sidebars.js`
- Page index: `$DOC_REPO/docusaurus/static/llms.txt`

2. **Parse `$FILTERED_PRS`** to get the list of PRs.

3. **For each PR:**
- Read `/tmp/pr-<NUMBER>-body.txt` and `/tmp/pr-<NUMBER>.diff`
- If the diff exceeds 3000 lines, mark as `skipped` with reason "Diff too large"
- Otherwise, apply the Router logic to decide if docs need updating

4. **Write the routing result** to `/tmp/router-results.json` using this exact schema:

```json
{
"prs": [
{
"number": 12345,
"title": "feat: add feature X",
"decision": "has_targets",
"complexity": "full",
"reason": "",
"targets_yaml": "targets:\n - path: cms/features/x.md\n action: update_section\n priority: primary\n existing_section: \"Configuration\"\n description: \"Add feature X config options\"\n\ndoc_type: feature\ntemplate: null\nguide: agents/authoring/AGENTS.cms.features.md\nconfidence: high"
},
{
"number": 12350,
"title": "fix: add missing link to REST API page",
"decision": "has_targets",
"complexity": "micro",
"reason": "",
"targets_yaml": "targets:\n - path: cms/api/rest.md\n action: add_link\n priority: optional\n description: \"Add link to new filtering guide\"\n\ndoc_type: api\nconfidence: high"
},
{
"number": 12346,
"title": "fix(admin): internal race condition fix",
"decision": "skip",
"complexity": "",
"reason": "Internal admin UI bug fix, no public API or behavior change",
"targets_yaml": ""
},
{
"number": 12347,
"title": "enhancement: add new CLI command",
"decision": "ask_user",
"complexity": "",
"reason": "Uncertain whether this CLI command is public-facing or internal tooling",
"targets_yaml": ""
}
]
}
```

**`decision` must be one of:** `has_targets`, `skip`, `ask_user`

**`complexity`** (only when `decision` is `has_targets`):
- `"micro"` — ALL targets are micro-edits (`add_link`, `add_mention`, `add_tip`). Haiku can handle these.
- `"full"` — at least one target is `create_page`, `update_section`, `add_section`, or `create_category`. Requires Sonnet.

**`targets_yaml`** is the full Router YAML output (as a string), only when `decision` is `has_targets`. Include `doc_type`, `template`, `guide`, `confidence`, and the full `targets` block.

## Step 5 — Execute micro-edits (if all targets are micro)

If a PR has `complexity: "micro"`, you handle the full pipeline yourself — no Sonnet needed.

For each micro target (`add_link`, `add_mention`, `add_tip`):
1. Read the target file from `$DOC_REPO/docusaurus/docs/<path>`
2. Apply the edit (add the link, mention, or tip)
3. Write the modified file back

Then create the branch and PR:

```bash
cd $DOC_REPO
BRANCH_NAME="<prefix>/<short-kebab-description>"
git checkout -b "$BRANCH_NAME"
git add .
git commit -m "<DOCS_CHANGE_DESCRIPTION>"
git push -u origin "$BRANCH_NAME"
gh pr create \
--repo strapi/documentation \
--title "[Docs self-healing] <DOCS_CHANGE_DESCRIPTION>" \
--body "$(cat <<'BODY'
This PR updates documentation based on https://github.com/strapi/strapi/pull/<NUMBER>.

Generated automatically by the docs self-healing workflow (micro-edit, Haiku).
Review before merging.
BODY
)" \
--draft \
--label "auto-doc-healing"
git checkout main
git clean -fd
git reset --hard origin/main
```

**Title rules:** `[Docs self-healing]` prefix, imperative mood, no conventional prefix, describe the doc change.

After micro-edits, add the PR to the results file with `decision: "has_targets"` and record the doc PR URL.

Update `/tmp/router-results.json` to include a `doc_pr` field for micro PRs you handled:

```json
{
"number": 12350,
"decision": "has_targets",
"complexity": "micro",
"doc_pr": "https://github.com/strapi/documentation/pull/99",
...
}
```

## Rules

- **Do NOT read any agent prompts except `router.md`**
- **For micro-edits only:** you may read and modify documentation files and create branches/PRs
- **For full complexity:** do NOT modify files or create PRs — leave that for Sonnet
- **ONLY read diffs, the Router prompt, sidebars.js, llms.txt, and write the result file** (plus doc files for micro-edits)
- **Max 5 PRs per run.** Log extras to stdout for the next run.
- **NEVER run any write operation on strapi/strapi**
Loading
Loading