baya-monorepo/archive/clarify-chain/phase-7-skills-and-guardrails.md

Phase 7 — Skills & anti-drift guardrails

Depends on: Phase 1 (rules) and Phase 3 (reality) · Can run before or after Phase 6 · Size: one session

Goal

Two things:

1. Skills that match reality. The one existing skill was written before the UI overhaul; parts of it describe an app that no longer exists.
2. Guardrails so this doesn't happen again — the reason the cleanup was needed at all.

The division of labour, restated: a rule is a constraint that must never break → docs/rules/. A skill is a procedure for a recurring task → .claude/skills/. If you're writing "always do X", it's a rule. If you're writing "to do X: first…, then…", it's a skill.

---

Inputs

• .claude/skills/frontend-designer/SKILL.md — 21 KB, 10 sections (brand, tokens, typography, component library, layout, icons, hard rules, workflow, anti-patterns, Figma)
• docs/rules/ — Phase 1's output, so the skill can stop restating rules and link instead
• docs/flows/ — Phase 3's output, especially testing-setup.md and the mock-vs-real map
• The client code as it is after iterations 1–2
• .githooks/pre-commit (3.4 KB) + .githooks/README.md
• client/package.json scripts (check, lint:copy, test:ci) and the server's build/test commands

Outputs

.claude/skills/
  frontend-designer/SKILL.md    rewritten against current reality
  backend-feature/SKILL.md      NEW — adding a feature to the .NET server
  flow-testing/SKILL.md         NEW — boot, seed, and walk a flow end-to-end

Updated: .githooks/pre-commit, docs/rules/documentation.md (Phase 1 wrote the convention; this phase adds the enforcement note), and status-doc headers.

---

Steps

1. Rewrite frontend-designer

Reality-check every section against the code, then rewrite. Specifically at risk (confirm each):

• §5 Layout & page shells — the app is now mobile-scoped: a max-width container so the shell never stretches on desktop, and the nurse side moved from a drawer to a bottom navigation with grouped root pages that summarize their domain. Any desktop-sidebar guidance is obsolete except where admin still uses one.
• §6 Icons — the icon set was replaced wholesale in iteration 1. The old mapping guidance is dead.
• §2 Design tokens / §3 Typography — check against the current theme, including the reduced Paper border-radius.
• §7 Non-negotiable rules — most of these are now rules, not skill content. Cut them down to a link into docs/rules/client/, keeping only what's design-specific.
• §1 Brand / §4 Component library — verify the App* inventory against client/src/components/ (which currently holds ~40 feature components in addition to the shared kit).
• Add what's missing: forms are react-hook-form now, so the "build a form" procedure changes; and theme/language switches live only in settings, not in top bars.

Target: shorter than the current 21 KB, because the rules half moves out.

2. Write backend-feature

The procedure for adding a feature to the server, derived from how the 199 handlers are actually shaped: where the command/query goes, the handler and validator, the DTO, the controller action, the EF configuration and migration, the tests, and the doc updates it must trigger (docs/integration/domains/<domain>.md + the OpenAPI snapshot). Link to docs/rules/server/ for constraints; keep the skill to the sequence.

3. Write flow-testing

The procedure a session follows to actually exercise a flow: boot both sides per docs/flows/testing-setup.md, get an OTP, log in as the right seeded account, walk the flow, and — importantly — check the mock-vs-real map first so a "working" flow isn't just a mock answering. Include the reseed step for when the time-relative scenarios age out.

4. Extend the pre-commit hook

Read the existing hook first and match its style. Add warnings, not blocks — a hook that blocks commits gets bypassed, and then it protects nothing.

Warn when:

• files under server/src/**/Controllers/** or **/Handlers/** changed but nothing under docs/integration/ did → "API surface changed — update docs/integration/domains/… and refresh the OpenAPI snapshot."
• client/src/services/** changed but no docs/integration/ or docs/flows/ change → "a service domain changed — does a flow doc need updating?"
• a file under docs/status/ or docs/flows/ is committed with a Last verified: date more than ~30 days old → "this doc claims to be verified as of ."
• root CLAUDE.md, client/CLAUDE.md, or server/CLAUDE.md exceeds its line budget → "the rulebook is regrowing; move reference material to docs/rules/."

Document each warning in .githooks/README.md and in docs/rules/documentation.md.

5. Stamp the freshness convention

Ensure every file under docs/status/ and docs/flows/ carries > Last verified: <date> against <commit> as its second line, and that docs/rules/documentation.md names exactly which files must carry it and who updates it.

---

Verification

• No sentence in frontend-designer describes pre-iteration-1/2 behaviour — spot-check the layout, icon, and form sections against real components.
• No skill restates a rule that docs/rules/ owns; each links instead.
• The three skills' trigger descriptions don't overlap (a task should match exactly one).
• The pre-commit hook runs and its new warnings fire on a deliberate test commit — and never block one.
• Every docs/status/ and docs/flows/ file has a Last verified: line.

Definition of done

The skills describe the app that exists, and the next time someone changes an endpoint without touching a doc, something says so.

Handoff

(filled in by the agent that runs this phase)