Agent guidance corrections, 2026-08-28

• Status: in progress, opened 2026-08-28.
• Issue: #990: process(agents): the scaffold-then-wire rule exists and did not fire, because the prompt asked for a running page covers the largest of the four. The other three are corrections to existing guidance rather than new work, and are tracked here.
• Launch plan: none, this is tooling.

What is this?

Four corrections to agent guidance that a day of real use proved wrong or missing.

• All four are edits to .agents/ source, never the generated .claude/ copies, with npm run sync:skills afterwards.
• They ran LAST on 2026-08-28, deliberately. Her rule that morning was that optimizations run last unless actively blocking, and she named optimizing-first as the loop that leaves product work on the table by EOD. This is that rule being kept, on the day she stated it.

What are the four?

1. agenda-creation gains intensity levels, and normal is the default.

• Her words, 2026-08-28: "Adjust agenda creation intensity. Default should be normal and not use the workflow if possible. Comprehensive would use the workflow which would take a while."
• The skill says "invoke the workflow" with no conditional anywhere in it.
• Normal has to be the default because it is what already happens. The last two agendas were both written by hand, one after she killed the workflow mid-run at seven minutes. Guidance that says otherwise is describing a process nobody follows.

2. agenda-documentation still says "Session N" in its prose and its templates.

• Her own agendas say Task. A number is an identity, not a position, and the skill currently instructs RENUMBERING when the order changes, which breaks every reference to a task in a message, a commit or an issue.
• Flagged as a gap on 2026-08-27 and not fixed.

3. The scaffold-then-wire rule exists and did not fire.

• #990 carries three causes, and the third is the generalisable one.
• The design skill scopes the rule to "New" UI, so a reshape of an existing surface reads as out of scope.
• The dispatch prompt said "done when it renders in a browser", so the agent hit the definition of done it was handed.
• A skill loses to a prompt, every time, because the prompt is read last and states the acceptance criteria. That is the half worth codifying.

4. Two design skill facts that are simply wrong for apps/admin.

• It says review at Storybook port 6006 and scaffold with npm run new:story. Neither works for admin: 6006 carries zero admin stories and new:story searches apps/web only. Found 2026-08-28 while building Scaffold, which is why tooling/.storybook-admin/ on 6008 had to be discovered rather than read.
• It offers opacity as a fix for a readability complaint. Opacity composites text toward its surface, so a passing token silently fails: it cost the admin Dashboard two real axe violations that day.

What is being added on top of the four?

The DECIDED / STARTING POSITION convention for dispatch prompts.

• Adopted by the PM session on 2026-08-28 after two lanes overturned it in one afternoon.
• DECIDED: evidence behind it, load-bearing. Push back with an argument.
• STARTING POSITION: the PM has not been inside that surface and is giving a default so the lane is not blocked. Overturn freely.
• Both overturns were structural rather than careless: the PM was specifying behaviour in surfaces it had not been inside, while the lane was in them. A convention beats vigilance for that.

Three verification lessons, into verified-done.

• A test asserting CURRENT behaviour and a test asserting CORRECT behaviour look identical in a green run. Only writing the falsifying case tells them apart.
• Two arms failing for the same unrelated reason is a test that cannot WIN, which is the same defect as one that cannot lose, pointed the other way.
• A harness that cannot distinguish ABSENT from NOT-LOOKED-AT-YET reports absence either way. Seven false readings on 2026-08-28, and the dominant mechanism was waiting on a CLOCK rather than a CONDITION.

What is the current state?

In progress. This README first, then the four edits, then the syncs.

• The constraint that governs all of it is .agents/rules/project/writing-into-documents.md: a rule stated in prose while every template shows the old shape is a rule that will be broken. agenda-documentation carries a four-line session prompt template, and if the new gates do not appear IN that template, this has failed however good the prose is.

One tension in the design skill that must NOT be flattened.

• It says build Storybook-first. It also says a Storybook story makes a parked idea look official, which she objected to in her own words on 2026-08-03.
• Both are true. A scaffold built to get a design approved is not the same as a story legitimizing a feature nobody asked for, and the skill should say what SEPARATES them rather than leaving the two lines quietly contradicting each other.

What else is related?

• #990: process(agents): the scaffold-then-wire rule exists and did not fire, because the prompt asked for a running page
• #991: feat(admin): a shared Scaffold component whose required props make a placeholder declare its age and its wiring issue, which is where the 6006 and new:story findings came from.
• docs/projects/agent-workflow-hierarchy/design.md, which owns the routing test for which layer a piece of guidance belongs in.