Aron PrinsandClaude Opus 5
325c9eb819
## Why
The build derived `<title>` from the **sidebar label** and the
description from the **first paragraph clipped to 220 characters**. Both
are the wrong source. A sidebar label is written for a 240px-wide nav
that supplies its own context; a search result has none.
On production that produced:
- **7 pages titled "Overview"**, and 32 pages sharing a title with
another page
- **109 of 193 descriptions cut off mid-word**, and 174 over 160
characters (where Google truncates)
```
/guides/welcome/key-concepts/
BEFORE (220): ...and if you misunderstand them early, the product wi
```
Near-identical titles are the weak-differentiation signal behind
"crawled — currently not indexed", which is the exact symptom on this
property.
## What changed
`seo_title` and `seo_description` frontmatter on **every one of the 192
pages**, written by hand against each page's real content and optimised
for the click — lead with what the reader can do, name the concrete
things covered, no keyword stuffing, no repeating the title.
| | Before | After |
|---|---|---|
| Duplicate titles | 32 pages | **0** |
| Duplicate descriptions | — | **0** |
| Descriptions cut mid-word | 109 | **0** |
| Descriptions over 160 chars | 174 | **0** |
| Title length (incl. suffix) | up to "Overview" | **26–60** |
| Description length | 31–240 | **122–158** |
**No prose was rewritten.** I measured content overlap between the
colliding pairs first — only 17–23%, so these were always distinct pages
wearing the same label, not duplicate content. The `docs/` diff is **564
insertions, zero deletions**.
### Examples
```
BEFORE — all seven identical: "Overview | Paperclip Docs"
AFTER: "Adapters Overview" "API Overview" "CLI Overview"
"Deployment Overview" "Bundled Skills" "Optional Skills"
"Experimental Features"
BEFORE — both identical: "Issues | Paperclip Docs"
AFTER: "Issues: Creating and Tracking Work" /guides/day-to-day/issues/
"Issues API" /reference/api/issues/
```
```
/guides/getting-started/five-minute-path/
BEFORE (220): The shortest route from a running Paperclip instance to an agent that has
just completed work for you. After Paperclip is installed, the path takes
about 5 minutes: create a company, hire a CEO agent, approve its first s
AFTER (131): Install Paperclip, create a company, hire a CEO agent, and approve its
first strategy — a working AI company in about five minutes.
```
## Plumbing
- **`site/build-release.mjs`** prefers the authored fields; the derived
path stays only as a fallback the CI gate prevents ever reaching.
`<title>`, `<meta name="description">`, and the `TechArticle` JSON-LD
all read from the same source.
- **`site/app.js`** uses the same fields, so a client-side transition
cannot leave a different title on screen than the crawler was served.
Verified in-browser: navigating `/guides/day-to-day/issues/` →
`/reference/api/issues/` swaps to exactly the server-rendered values, no
JS errors.
- **`scripts/verify-seo-metadata.mjs`** (new) enforces presence,
uniqueness, length, complete-sentence endings, and the
frontmatter-safety rules. Wired into `docs:test` and CI as its own step.
I negative-tested the gate rather than assuming it works — it correctly
fails on a duplicate title, a mid-word description, and a missing field,
and passes again once restored.
## Automating it going forward
`skills/sync-docs/SKILL.md` now:
- gains an **"Authored SEO metadata"** section: why the fields exist,
the enforced rules as a table, and how to actually write them (title
names the subject not the nav position; description writes for the
click; never generate mechanically from the first paragraph — *that is
the fallback the gate exists to prevent*).
- requires both fields in the **page-authoring instruction** given to
every subagent, with guidance on when to update an existing description
versus leave it.
- runs `docs:test:seo-metadata` and `docs:test:crawlable-links` as
**fail-loud gates in Phase 7** before commit.
- documents all six build gates in the files/gates section.
So once this lands, a new page cannot ship without hand-written
metadata, and a title collision cannot reach production.
## Verified
All six verifiers pass:
```
Static route verification passed
Asset fingerprint verification passed
Hierarchical Skills nav verification passed
Skill source block verification passed (11 skill pages, 1 control page)
Crawlable-link contract passed: 40886 internal links across 194 pages resolve in one hop
Authored-SEO contract passed: 192 pages carry a unique, hand-written seo_title and seo_description
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
4.1 KiB
paperclip_version, seo_title, seo_description
| paperclip_version | seo_title | seo_description |
|---|---|---|
| v2026.707.0 | Task Plan Decomposition Panel | See the machinery that turns an accepted plan into child tasks, and the guarantee it runs exactly once even across retries and interrupted runs. |
Task Plan Decomposition Panel
When an agent's plan is accepted, Paperclip decomposes it into child tasks — and it guarantees that decomposition happens exactly once, even if the agent retries or a run is interrupted mid-creation. Normally that machinery is invisible: you just see sub-tasks appear. The Task Plan Decomposition Panel makes it visible.
It adds a read-only Plan decomposition section to task detail pages showing, per accepted plan revision, how many child tasks were requested, how many were actually created, and which ones — so you can validate that sub-task creation behaved correctly.
Why it exists
This panel is a debugging and validation surface. The app's own description is candid about it: "Intended for debugging and validating subtask creation behavior while the presentation is still being refined." Turn it on when you're diagnosing questions like "did this plan create all its sub-tasks?", "did a retry double-create children?", or "is a decomposition still in flight?" — and feel free to leave it off otherwise.
Turn it on
- Go to Settings → Instance settings → Experimental.
- Turn on Task Plan Decomposition Panel — "Show accepted-plan decomposition history on task detail pages."
The setting is instance-wide and takes effect immediately.
Reading the panel
Open a task whose accepted plan created sub-tasks. The Plan decomposition section appears in the main column, just above Documents, with a count of accepted plan revisions. Each revision gets a card:
- A status badge — Completed (green check) or In flight (amber spinner) while children are still being created.
- "Plan revision N" and the creation progress — "3 of 3 child tasks created".
- An "Idempotent claim" badge on completed records. This is the exactly-once guard: repeat attempts with the same fingerprint reuse this record instead of creating duplicate children.
- A metadata row — the owning agent, when the decomposition started and completed, and a link to the accepted Plan document.
- A chip for each created child task, linking to its detail page.
There's nothing to configure and nothing to click besides the links — the panel is purely informational.
Note: the panel only renders on tasks that actually have decomposition history. A task whose plan never spawned children shows nothing, even with the flag on.
Where it lives with Chat-Style Tasks on
This page describes the classic task page. If you also run the Chat-Style Tasks experimental feature, the same decomposition history moves into the task's properties panel, on a Plan tab that shows the plan document itself with the accepted-plan history underneath it — so you read the plan and what it created in one place.
Two things worth knowing about that arrangement:
- The centre-column Plan decomposition section described above is hidden while Chat-Style Tasks is on. It hasn't gone anywhere; it's in the Plan tab.
- The Plan tab shows the history on its own, without this Task Plan Decomposition Panel flag. Turning this flag off hides the section from the classic task page, but the Plan tab keeps showing accepted plans as long as Chat-Style Tasks is on.
See Issues for the rest of what the Plan tab holds, including approving a plan from the panel.
When it's off
Purely hidden. Decomposition records still exist and the exactly-once guards still run — the flag only controls whether the history is displayed. Flip it back on and the history reappears.
Where to go next
- Work Modes — how plan-mode tasks produce plans that get accepted and decomposed.
- Issues — sub-tasks, blockers, and the task detail page.
- Experimental features overview