Merge pull request #5 from JuliusBrussee/claude/last-20-percent-skill-wv1ork

Add last-20-percent skill for finishing the experiential layer agents skip

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This repo publishes seven Julius Brussee agent skills for now: `caveman`, `interface-kit`, `grill-me`, `loop-factory`, `junior-to-senior`, `fuck-slop`, and `context-canary`. Treat it as an installable skill collection, not a product website.
+This repo publishes eight Julius Brussee agent skills for now: `caveman`, `interface-kit`, `grill-me`, `loop-factory`, `junior-to-senior`, `fuck-slop`, `context-canary`, and `last-20-percent`. Treat it as an installable skill collection, not a product website.
 
 ## Editing Rules
 

README.md

@@ -4,9 +4,9 @@
 
 # Julius Skills
 
-Seven personal agent skills for now: Caveman base, Interface Kit, Grill Me, Loop Factory, Junior to Senior, F*ck Slop, and Context Canary.
+Eight personal agent skills for now: Caveman base, Interface Kit, Grill Me, Loop Factory, Junior to Senior, F*ck Slop, Context Canary, and The Last 20%.
 
-This repo is shaped by seven things:
+This repo is shaped by eight things:
 
 - **Caveman** - 70k-star token compression without technical loss. Small mouth, big brain.
 - **Interface Kit** - accessible, performant interfaces with strong aesthetic direction, not generic AI slop.
@@ -15,6 +15,7 @@ This repo is shaped by seven things:
 - **Junior to Senior** - adversarial senior review that treats agent output as junior work and upgrades it with codebase + web research.
 - **F*ck Slop** - mechanical scan-and-rewrite loop that erases AI-writing tells from any text and lands it in the right register.
 - **Context Canary** - per-turn canary signal that makes silent context degradation visible, plus a recovery protocol when it trips.
+- **The Last 20%** - finds and finishes the experiential layer agents skip: what the output reads like, which pages exist, first-run, defaults, the golden path.
 
 Point is control. Agents should be terse when talking, precise when building interfaces, calibrated when challenging plans, and disciplined when running build loops.
 
@@ -133,6 +134,18 @@ Use when you want:
 
 Grounded in context-rot research (Chroma), lost-in-the-middle (Liu et al.), and instruction-drift findings — sources linked in the skill's references.
 
+### `last-20-percent`
+
+Finds and finishes the last 20% of a built solution — the experiential layer agents skip. Agents decompose the noun ("wiki" → ingestion, search, LLM) and the experience of using the thing never appears in that decomposition, so it never becomes a task. This skill decomposes the *scene* instead: one concrete magic moment, walked step by step, with the residue specced at plumbing fidelity and hand-crafted golden artifacts set as the quality bar before any generator gets built.
+
+Use when you want:
+
+- builds that end with a product, not a technically-complete demo
+- the experiential work (content, IA, first-run, defaults, microcopy) specced as concretely as the plumbing
+- golden artifacts written by hand before the machinery that generates them
+- a final walk-through as the end user before anything is called done
+- an audit mode for existing solutions that work but feel flat
+
 ## Interface Kit Standard
 
 If a repo has `DESIGN.md`, it wins. Otherwise UI work should still have a point of view:

skills/last-20-percent/SKILL.md

@@ -0,0 +1,92 @@
+---
+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, navigation) threaded through the build, decided at the moment the relevant plumbing is built, not batched for "polish week."
+3. Keep the scene list visible as a **finish list** in the plan or tracker, each item with its done-criteria. Treat an unchecked finish-list item exactly like a failing test: the build is red until it's green.
+
+## Phase 5: The walk
+
+When the build claims to be done, become the end user — cold, no insider knowledge. Perform the magic moment literally: go where Sarah would go, type what she'd type, read what she'd read, all the way through.
+
+Judge what you find against the golden artifacts and the finish list. Then write down every gap between the walk and the scene: pages that read like filler, a dead-feeling first run, a default that made you decide something the product should have decided. Fix, and walk again. The loop ends in one of two states:
+
+- The walk delivers the magic moment → say so, show the evidence (the actual pages read, the actual flow taken), and stop.
+- The remaining gaps need a human product decision → list them explicitly as decisions with a recommended option each, and stop there.
+
+## Modes
+
+- **Plan mode** — a build request just arrived. Run Phases 1–4 to shape the plan before or alongside the noun-list work, then Phase 5 before declaring done.
+- **Audit mode** — a solution already exists ("is this actually done?", "why does this feel like a demo?"). Start with the walk (Phase 5) to gather evidence, backfill the magic moment and scene list (Phases 1–2), then spec and finish the gaps (Phases 3–4) and walk again.
+
+## Boundaries
+
+- **The last 20% is depth on the core scene, never breadth.** Adding features is the opposite failure wearing a finishing-touches costume. If an idea doesn't serve the magic moment, it goes to a someday list.
+- **Bring a take.** Propose defaults, page structures, and voice with reasons. Reserve questions for decisions that are genuinely irreversible or genuinely business-strategic — and even then, attach a recommendation.
+- **Don't gold-plate the plumbing.** This skill spends its budget on the experiential residue, not on rewriting working infrastructure to be prettier inside.
+- **A solution is allowed to pass.** If the walk delivers the moment, say "this is done" and stop. Manufacturing gaps to look thorough is its own kind of slop.

skills/last-20-percent/references/last-20-catalog.md

@@ -0,0 +1,90 @@
+# The Last 20% Catalog
+
+The recurring categories the scene-list residue falls into. For each: what it is, the probe question to ask of any build, and worked examples across domains. Use this after decomposing the scene (Phase 2) — run the build against every category and probe; anything that lands unanswered goes on the finish list.
+
+## 1. Content and voice
+
+What the system's output actually reads like, sentence by sentence. This is the single most-skipped category: the machinery to *produce* content gets built, and the question of what good content *is* never gets asked.
+
+**Probe:** Pick one real artifact the system will produce. Could you write out, right now, the ideal version of it by hand? If not, nobody has decided what the output should be.
+
+- *Knowledge wiki:* Does a page open with the answer or with boilerplate ("This page describes...")? Are headings the questions readers ask, or the names of database fields? Does every claim cite its source doc?
+- *Report generator:* Does the report lead with the finding or with methodology? Is there a one-paragraph executive summary a director would actually forward?
+- *Chatbot / assistant:* Does it have a register — terse, warm, formal? Or does every reply read like the average of the internet?
+- *Code generator:* Does emitted code match the host repo's idioms, or a generic style no reviewer would approve?
+
+## 2. Information architecture
+
+Which pages, screens, sections, or commands exist, and why those. The noun list produces a data model; it never produces an answer to "what does the table of contents look like?"
+
+**Probe:** Draw the sitemap (or screen map, or command tree) from memory. If it's just "list view + detail view" or "one page per database row," nobody designed it.
+
+- *Wiki:* What page *types* exist — overviews, how-tos, policy pages, glossaries? One page per source document is ingestion leaking into IA; readers need pages organized by question, not by file.
+- *Dashboard:* Which questions does each view answer? A dashboard that shows "all the metrics" answers none of them.
+- *CLI tool:* What does `--help` print, and is the most common workflow the shortest command?
+- *API:* Do the endpoints map to consumer intents, or mirror internal tables?
+
+## 3. First-run and empty states
+
+What the person sees on day zero, before there's data, history, or content. Builds get tested against a populated fixture; users arrive at an empty one.
+
+**Probe:** Delete all the data and open the product. Is what you see an invitation or a wall?
+
+- *Wiki:* Before ingestion finishes — a spinner, or a starter set of hand-seeded pages proving what the wiki will be?
+- *Dashboard:* No events yet — blank charts, or a guided "send your first event" path with example output?
+- *SaaS app:* Fresh account — a barren table, or a worked example the user can poke at and then replace?
+
+## 4. Opinionated defaults
+
+Every configuration surface is a decision the product refused to make. The 80% instinct is to make everything configurable; the 20% is choosing well so nobody has to configure anything.
+
+**Probe:** List every option, flag, and setting. For each: what happens if a user never touches it? If the answer is "the product is worse," the default is wrong or the option shouldn't exist.
+
+- *Wiki:* Which model, which chunk size, which page template? Ship the choice, note it in one line, let power users override later.
+- *Report generator:* Default period, default recipients, default format — a report that asks five questions before running will never be run.
+- *CLI:* Zero-flag invocation should do the most common thing correctly.
+
+## 5. The golden path
+
+The one flow that must feel effortless — the scene from Phase 1, end to end. Everything else can be merely functional; this one path has to be fast, obvious, and dead-end-free.
+
+**Probe:** Time yourself performing the magic moment cold. Count the steps where you hesitated, guessed, or needed knowledge only the builder has. Each is a gap.
+
+- *Wiki:* Question in head → answer on screen. How many clicks, and was any of them a guess?
+- *Internal tool:* Is the golden path reachable from wherever users actually start (Slack, a bookmark, an email link), or only from a URL nobody knows?
+- *Library / SDK:* The README's first code block *is* the golden path. Does it run as pasted?
+
+## 6. The failure experience
+
+Errors get *handled* in the 80% (caught, logged, retried). What the person *experiences* at that moment is 20% work.
+
+**Probe:** Force the three most likely failures — no results, bad input, upstream down — and read what appears on screen as a stranger. Does it tell them what happened and what to do next, in their vocabulary?
+
+- *Wiki search, zero hits:* Bare "no results," or the three nearest pages plus a "request this page" action?
+- *Ingestion, one bad document:* Silent skip, or a visible note on the affected pages that a source failed?
+- *API:* Do error bodies name the fix ("field X must be ISO-8601") or just the failure?
+
+## 7. Naming and microcopy
+
+Titles, labels, button text, section names, empty-state sentences. Tiny surface, outsized effect — this is most of what a user actually reads, and builders leave placeholder names in it ("Untitled", "Home", "Data", "Submit").
+
+**Probe:** Read every string a user will see, out loud, in one sitting. Flag anything a builder wrote for themselves: internal jargon, table names, "TODO", or copy so generic it could sit on any product.
+
+- *Wiki:* Is the wiki itself named? Do page titles read like answers ("How contract review works") or like keys ("contract_review_v2")?
+- *Dashboard:* Are metrics labeled in the reader's language ("Signups this week") or the pipeline's ("dim_user_cnt_7d")?
+
+## 8. The second visit
+
+Whether the thing gets better with use — or at least remembers you came. Demos optimize the first impression; products live on return visits.
+
+**Probe:** Use it, leave, come back tomorrow. What's different? If the answer is "nothing," the product has no memory and no pull.
+
+- *Wiki:* Do fresh pages get flagged? Do stale ones warn? Is there a "recently answered" trail that makes the wiki feel alive?
+- *Dashboard:* Does it open on what changed since you last looked, or on the same static default?
+- *Assistant:* Does it recall context from last time, or start every session as a stranger?
+
+---
+
+## Using the catalog
+
+Not every category applies to every build — a batch job has no microcopy to speak of; a library has no empty state. Run all eight probes anyway; deciding a category is N/A takes seconds, and the skipped 20% is by definition the part you didn't think to check. Every probe that lands unanswered becomes a finish-list item with concrete done-criteria (Phase 3).