Agent guidance corrections: what to review

Field	Value
Branch	feat/admin-and-merchant-portals, draft PR #976: feat(admin): portal navigation, financials and monitoring, plus the agent-process work behind them, not merged
Project	README.md
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
Servers you need	None. There is nothing to click. These are edits to .agents/ sources and their generated copies
Local origins	Not applicable

Is there anything to look at?

The diff on .agents/, and two commands that prove the generated copies match their sources.

node tooling/scripts/lint.sync-skills.js
node tooling/scripts/sync-agents.mjs --check

• All four corrections are edits to .agents/ source, never the generated .claude/ copies. If a check reports drift, a copy was edited directly and the next sync will overwrite it.
• The files worth reading in the diff: .agents/skills/agenda-creation/skill.md, .agents/skills/agenda-documentation/skill.md, .agents/skills/design/skill.md, .agents/skills/verified-done/skill.md.

What changed here?

These ran LAST on 2026-08-28, deliberately, on the day you stated the rule.

• Your rule that morning: an optimization runs last unless it is actively blocking, and you named optimizing-first as the loop that leaves product work on the table by EOD. This is that rule being kept.

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

• Your words: "Default should be normal and not use the workflow if possible. Comprehensive would use the workflow which would take a while."
• Normal has to be the default because it is what already happens. The last two agendas were both written by hand, one after you killed the workflow mid-run at seven minutes. Guidance that says otherwise is describing a process nobody follows.

2. agenda-documentation said "Session N" while your own agendas say Task.

• A number is an identity, not a position, and the skill instructed renumbering when the order changes, which breaks every reference to a task in a message, a commit or an issue.

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

• The design skill scopes it to "New" UI, so a reshape of an existing surface read 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, plus one that is wrong everywhere.

• It said 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.
• That is why tooling/.storybook-admin/ on 6008 had to be discovered rather than read.
• It offered 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.

Plus the DECIDED / STARTING POSITION convention for dispatch prompts.

• Adopted after two lanes overturned a PM instruction in one afternoon.
• DECIDED: evidence behind it, load-bearing, push back with an argument. STARTING POSITION: 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.

Plus three verification lessons, into verified-done.

• A test asserting CURRENT behaviour and one 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 deliberately NOT done?

One tension in the design skill was left standing on purpose, and it must not be flattened.

• It says build Storybook-first. It also says a Storybook story makes a parked idea look official, which you objected to in your 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. The skill should say what SEPARATES them rather than leaving the two lines quietly contradicting each other. That separation has not been written.

Three of the four are corrections to existing guidance rather than new work, so they carry no issue of their own.

What open findings touch this project?

• Nothing from ../merchant-and-venue-dashboards/branch-review-0828.md. No .agents/ finding was raised.
• The related gate is in a sibling project: the docs-format invariants checker is what would catch a rule stated in prose while every template shows the old shape. See ../docs-format-invariants/testing.md.

What issue does each piece close?

Piece	Issue	State
The scaffold-then-wire rule not firing	#990: process(agents): the scaffold-then-wire rule exists and did not fire, because the prompt asked for a running page	Open, three causes carried
Where the 6006 and new:story findings came from	#991: feat(admin): a shared Scaffold component whose required props make a placeholder declare its age and its wiring issue	Built on branch
Nothing covers how to WRITE a skill	#1001: docs(agents): nothing covers how to WRITE a skill, only when to and what shape it takes	Open, adjacent