working-backwards · git:20261020.9e7d19a · 2026-10-20 · sha256 0261b4c5b443c02a
working-backwards git:20261020.9e7d19aA
Immutable. This exact content never changes and is served at /api/v1/blob/0261b4c5b443c02a.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_izb32ujo66hal4db/0261b4c5b443c02a3524364cddeac500433db07c49a6e63b697a973114f38eaf.json
Then /plugin install working-backwards@markdownregistry-izb32ujo66hal4db in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: working-backwards description: Amazon-style PR/FAQ for a user-facing Duct feature. A customer press release and FAQ written on the issue before any code, revised against what actually shipped at merge, then a launch triage that picks the outlet (a changelog line, a blog post through add-blog-post, an integration page, a landing page section) or records why there is none. Use for "write the PR/FAQ", "working backwards on #N", "launch this feature", "should this feature get a blog post". argument-hint: "<issue number> | ship <issue or PR number>" --- Every user-facing feature gets a **PR/FAQ**: a one-page press release and a FAQ, written for the person who will use it, before the first commit. Not every feature gets a **blog post**. The PR/FAQ is the thing that is always written; a post is one of several places its words can end up, and most features end up in the changelog alone. That split is deliberate, and it is worth knowing why before arguing for "a post per feature": - **The blog already has a bar.** `add-blog-post` publishes nothing a reader could not get elsewhere, at one post every two weeks, because one cited page beats five thin ones. A feature post that clears that bar goes through it; one that does not is a page to maintain that nobody, reader or answer engine, has a reason to pick. - **Search engines discount pages made in bulk.** Google's scaled content abuse policy is about many pages produced mainly to rank, whatever produced them. This repo already refuses pair pages on the integrations hub for the same reason (`site/AGENTS.md`, "Integrations"). An agent-written post for every merge is that pattern with a blog template on it. - **Announcement posts cannibalize.** Few people search "Duct now does X". When one does collect links, it keeps ranking long after the feature changed, ahead of the integration or landing page that should own the query. So the measure of this skill is not posts published. It is that every feature was described in the customer's words before it was built, that the description was checked against what shipped, and that the words went wherever they do the most work. ## What counts as user-facing Anything that changes what a person using Duct sees or can do: a new connector, a new kind of insight, a new action Duct can take, a change to approvals, models, pricing, the desktop app. Not: refactors, CI, internal tooling, a flag still off, and bugs. A bug fix restores something already promised; the changelog carries it and it needs no PR/FAQ. ## Mode 1: draft (before code) Run it while the issue is being specced, as part of `prioritize`'s "Writing it up" for an `enhancement` that is user-facing, and before the first commit. Read first: the issue, [`README.md`](../../../README.md) for the job Duct does, and [`site/AGENTS.md`](../../../site/AGENTS.md)'s "What the desktop app actually is", because the press release is the first place a false promise about the product gets written down. ### The press release At most one page, around 300 to 400 words. Dated the milestone's due date and written as though that day has come. ```markdown ## Press release **<Headline: what the reader can now do, in their words, under 10 words>** <Subhead: who it is for and the outcome, one sentence> <Mon D YYYY>. <Summary: the reader, the job, what changed, in two or three sentences. Someone who stops here knows everything that matters.> <The problem: the situation today, in the tools they already use, with a number where one exists. Two signals that disagree is the house shape: "Search Console says impressions are up. GA4 says trials are flat."> <The solution: what they do in Duct now, step by step, as they would experience it. Name the third-party tools. Say where Duct waits for them to approve.> > "<What this persona would say after a week of using it.>" > (hypothetical: <persona, role>) <Getting started: one sentence, the first click.> ``` Rules, all checkable: - **The reader's job, not the feature's name.** "See which pages are losing clicks before the monthly report does", not "Introducing Content Decay Alerts". If the headline cannot be written without the feature's internal name, nobody outside the repo has the problem in those words yet. - **The quote is marked hypothetical** and never leaves the issue unless a real user says it, by name and with permission. A made-up customer quote in published copy is a fabricated review. - **No file paths, module names, PR numbers or internal jargon.** This is the end-user document; the spec beside it is for the people building. - **Nothing the milestone will not ship.** No roadmap, no "coming soon". - **The house voice** ([`site/DESIGN.md`](../../../site/DESIGN.md), "Voice"): numbers over adjectives, the founder test, American spelling, and no em dashes, because these sentences become post and changelog copy. Words that fail review on sight: seamless, powerful, leverage, unlock, revolutionize, AI-powered, game-changing, excited to announce. ### Customer FAQ Five to eight questions a person would ask before trying it, each answered in 40 to 60 words that stand alone. That length is the blog's FAQ rule, so the answers move into a post, an integration page or a landing page FAQ without a rewrite. Always answer the ones that apply: - What does it read, and what can it change? Does a change wait for me? - What does it cost me? On the user's own model keys a run lands on their provider bill: say roughly how much per run, not "it depends". - Where does my data go? (The downloaded app talks to Duct's cloud; say so.) - How is this different from what <the third-party tool> does on its own? - What does it not do yet? ### Internal FAQ: only what the spec does not already say `prioritize`'s spec already holds the options considered, non-goals, the smallest shippable version and done-means. Do not restate them. The internal FAQ adds the questions that spec format skips: - **Unit cost.** What one run costs in tokens and third-party API quota, and who pays: the user's keys, or Duct's hosted account. Show the arithmetic. - **The metric that moves**, and the event it is read from (PostHog or GA4), so done-means is observable and not a feeling. - **Search demand for the job**, not the feature: `python3 .agents/skills/add-blog-post/research.py "<the job, as people type it>"`. It costs a minute now and decides the launch triage in Mode 2 early. - **The riskiest assumption**, and the cheapest way to test it before the build (`prioritize`'s third question). The repository is public and so are its issues. No revenue, no customer names without consent, nothing from the private GTM plan. ### The draft is a test If the problem paragraph cannot name a person who has this problem today, the feature fails `prioritize`'s first question. Say so, and close or park the issue under `prioritize`'s rules. That is the PR/FAQ doing its job, not failing at it: Amazon writes these before building precisely so that some of them stop the build. ### Where it goes On the issue, in its body: `## Press release` and `## Customer FAQ` above the spec sections, `## Internal FAQ` below them. `gh issue edit <n> --body-file <file>`, or the GitHub MCP `issue_write` tool where `gh` is not available. ## Mode 2: ship (at merge) Run it when the pull request that closes the issue is merged or ready to merge. The PR template's **Launch** line asks for the result. ### 2a. Diff the promise against what shipped Read the merged diff, not the PR description. For every sentence of the press release and every FAQ answer, mark it true, changed or cut, checked against the code: the harness post once said a person approves "anything that spends money", the execution policy said otherwise, and only reading the policy caught it. Post the revised press release and FAQ as a comment on the issue, headed `## Launch: what shipped`. Leave the draft in the body as it was written: the distance between what was promised and what shipped is worth seeing later, and an edited draft hides it. ### 2b. Pick the outlet Every user-visible change gets its changelog line through `add-changelog-entry`, at the next release; the shipped headline is usually that bullet's lead phrase. Beyond the changelog, pick **at most one**: | The feature… | Outlet | Through | |---|---|---| | adds a connector | its integration page copy, which is the page that should own "<tool> + Duct" searches | `scripts/integrations/connectors.py`, `build_integrations.py` | | automates a job people already search for (Mode 1's demand check found the phrasing) | a **Growth** post that teaches the job, with the feature as the evidence | `add-blog-post`, category Growth | | changes what Duct is for someone deciding whether to install: a new class of capability, a new platform, a change to how models or pricing work | an **Announcement** post | `add-blog-post`, category Announcement | | sharpens the pitch to an audience that already has a page | a section or FAQ entry on that `for-*` page | `site/AGENTS.md`, "New landing page" | | none of the above | the changelog line, and the decision recorded | nothing else | A post is chosen only when all three hold: 1. It clears `add-blog-post`'s value bar: the reader can do or knows something after it they could not before. 2. Its primary query is not already owned by another page on getduct.ai. Check `site:getduct.ai <query>`, the sitemap, and Search Console through Duct. If a page owns it, improve that page instead. One primary query per URL. 3. It fits the calendar. It is filed as a `post: <working title>` issue and takes the next slot for its cluster under `add-blog-post`'s cadence. Several features in one milestone share **one** Announcement post; the changelog's release name is usually its theme. Record the decision on the issue in one line, so nobody re-asks: ``` Launch: changelog only | post #<n> | integration page | for-<page> section, because <one line> ``` "Changelog only, because the feature has no search demand and no page owns its job yet" is a finished outcome, the same kind of artifact as a published post. ### 2c. Hand a post to add-blog-post The PR/FAQ is the brief's first draft, not a replacement for the research. Open the `post:` issue with these fields filled, then run `add-blog-post` from Phase 1b (who answer engines cite today) onward: | Brief field (`add-blog-post`, 1e) | From the PR/FAQ | |---|---| | Reader | the subhead's persona | | Primary question | the job's search phrasing from Mode 1, never the feature name | | Secondary questions | the Customer FAQ | | The value | the solution paragraph, as shipped | | Duct's first-hand evidence | the merged PR, the metric from the internal FAQ, a product shot (`scripts/shots/shoot.mjs`) | | What it does not do | the "not yet" answer | A post that starts here is for the person using Duct, not for contributors, which changes a few of `add-blog-post`'s defaults: - **The title is the job**, the same rule as the headline. - **Evidence is the product, not the code.** A product shot and the integration page, not a link to a source file. Code links belong to Engineering posts, which this skill does not write. - **Announcement is the one category where Duct is the subject.** The no-pitch rule still holds as no superlatives and no "excited to announce": say what the reader can now do, show it, and say what it cannot do yet. ## Done means **Draft** - [ ] Press release under one page; the headline is the reader's job; the quote is marked hypothetical - [ ] Customer FAQ of 5 to 8, each answer 40 to 60 words and standalone; cost and data answered plainly - [ ] Internal FAQ holds only unit cost, the metric, search demand and the riskiest assumption - [ ] Every claim true of the product as `site/AGENTS.md` describes it; nothing private in a public issue - [ ] On the issue body; or the feature stopped at `prioritize`'s first question, and that is recorded **Ship** - [ ] Every sentence checked against the merged code; `## Launch: what shipped` posted; draft left as written - [ ] Outlet chosen from the table, at most one beyond the changelog, and the `Launch:` line recorded on the issue and the PR - [ ] For a post: the three tests pass, the `post:` issue is filed with the brief filled, and `add-blog-post` takes it from 1b