baya-monorepo/docs/_plan/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](../../.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](../../.githooks/pre-commit) (3.4 KB) + [.githooks/README.md](../../.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 <date>."*
- 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)_