/last-20-percent

name: last-20-percent
description: >
  Finds and finishes the last 20% of a built solution — the experiential layer
  agents skip: what the output actually reads like, which pages or screens
  should exist, first-run and empty states, opinionated defaults, the golden
  path. Use when planning any build so the magic gets specced as concretely as
  the plumbing, before calling any build "done", when a solution works but
  feels like a demo, or when the user says "last 20%", "finish this", "make it
  actually good", "is this actually done", or "why does this feel flat".

The Last 20%

Agents reliably deliver the first 80% of a solution — the ingestion, the endpoints, the schema, the pipeline — and quietly skip the 20% that makes it something a person would love. Asked for an enterprise knowledge wiki, an agent builds the crawler, the embeddings, the LLM synthesis layer, and never once asks what a wiki page should *read like*, which pages should exist, or how someone finds an answer on day one. The result compiles, passes tests, demos fine, and is dead on arrival.

This skill exists to find that 20%, spec it as concretely as the plumbing, and finish it.

Why the 20% gets skipped

The failure is structural, so the countermeasures must be too:

1. **Tasks come from the noun.** Decomposing "wiki" yields ingestion, storage, search, generation. The experience of *using* the wiki never appears in that decomposition — so it never becomes a task, so it never gets done. 2. **"Done" is defined by what's checkable.** A test can assert a 200 response. It cannot assert "this page answers the question in its first paragraph." Work without done-criteria silently drops off the plan. 3. **Taste feels like overreach.** Deciding what a page should read like is a product judgment. Models hedge: they build "flexible" machinery and defer every real decision to a user who asked precisely because they wanted those decisions made. 4. **The 20% is scheduled last, and last gets cut.** Even when the experiential work is named, it lands at the end of the plan — exactly where context, budget, and attention run out.

Each phase below counters one of these.

The cardinal rule

**Never call a solution done until you have consumed its output the way the end user will — and it delivered the magic moment.** Reading your own code is not consuming the output. Passing tests is not consuming the output. Open the wiki and read three pages cold. Run the report and read the report. Load the dashboard and try to answer a real question with it.

Phase 1: Write the magic moment

Before decomposing anything, write one concrete scene: a named person, a real task, what they see, and why they'd tell a colleague about it afterward.

Bad (a feature): "Users can search the wiki." Good (a scene): "Sarah from legal types 'data retention' and lands on a page whose first paragraph answers her actual question, with a link to the policy doc it came from. She stops asking in Slack."

The scene is the destination for everything that follows. If you cannot write it, that gap *is* the missing 20% — stop and close it first. Propose two or three candidate scenes with a recommendation; never hand the user a blank page to fill in.

Phase 2: Decompose the scene, not just the noun

Build two lists:

• **The noun list (the 80%).** What you get by decomposing the deliverable's name. Ingestion, auth, schema, API, deploy. Agents produce this list automatically; it needs no help.
• **The scene list.** Walk the magic moment step by step and write down everything that must be true for it to happen. What did Sarah type into, and how did she know to go there? What did the page look like when it loaded? Why was the answer in the first paragraph and where did the link come from? What would she have seen on day one, before ingestion finished?

**The last 20% is the scene list minus the noun list.** That residue is not random — it falls into recurring categories: content and voice, information architecture, first-run and empty states, opinionated defaults, the golden path, the failure experience, naming and microcopy. The full catalog, with probe questions and worked examples across domains, is in [references/last-20-catalog.md](references/last-20-catalog.md) — run the scene list against it to catch what the walk-through missed.

Phase 3: Spec the 20% at plumbing fidelity

Every scene-list item gets done-criteria as concrete as "endpoint returns 200". Vague quality goals are how this work dies; convert each one into something checkable:

• "Pages should be readable" → "Every page opens with a 2–4 sentence direct answer before any detail; section headings are the questions readers actually ask; every claim links to its source document."
• "Good empty state" → "A search with zero results shows the three closest pages and a one-click 'request this page' action — never a bare 'no results'."

Golden artifacts

When the system produces artifacts — wiki pages, reports, emails, dashboards, generated code — **hand-craft the best possible instance before building the generator.** Write the ideal wiki page yourself, with real content about a real topic from the actual corpus. That golden artifact becomes three things at once: the spec (this is what output looks like), the test fixture (compare generated output against it), and the quality bar (a generator that can't approach it isn't done).

A generator built without a golden artifact converges on generic filler, because "generate a wiki page" with no exemplar means "produce the statistical average of all wiki pages." And never use lorem ipsum or placeholder content in a golden artifact — fake content hides whether the structure actually works.

Phase 4: Front-load, never append

In build mode, refuse to schedule the 20% last. Order the plan so the experiential layer survives:

1. Golden artifacts first — before the machinery that produces them. 2. Experience decisions (page types, defaults, voice, na