Fret Skills Playbook

Fret skills playbook (shared conventions)

This skill is the shared “glue” for the rest of the Fret skill set: it defines conventions that keep agent work reviewable, reproducible, and architecture-aligned.

When to use

• You are writing or updating a skill.
• You want consistent outputs across different contributors/agents.
• You are unsure what regression gate + evidence artifacts to leave behind.

Inputs to collect (ask the user)

• What is the user-facing invariant (correctness, UX, parity, perf)?
• What is the smallest runnable target (demo/gallery/script) that shows it?
• Is the work about a first-party teaching surface (for example UI Gallery) or an internal recipe/runtime surface?
• Which layer should own the change (mechanism vs policy vs recipe)?
• What artifacts must be produced (gate + evidence)?

Defaults if unclear:

• Start from the smallest runnable demo and leave a regression artifact + evidence anchors.
• When first-party examples are involved, treat UI Gallery snippet files as the exemplar source of truth.

Smallest starting point (one command)

• python3 .agents/skills/fret_skills.py validate --strict

Quick start

• Read references/execution-mode-selection.md when deciding whether the task should stay fast, become a quick slice, or move into a workstream.
• Read references/goal-backward-verification.md when deciding what must be proven before calling work “done”.
• Use the “deliverables 3-pack” for any non-trivial change:
  • Repro (smallest target or script)
  • Gate (test/script/perf)
  • Evidence (anchors + command)

Workflow

1) Layering decision (non-negotiable)

Use this rule of thumb:

• crates/*: mechanisms and hard-to-change contracts (routing, focus primitives, overlay roots, layout/semantics).
• ecosystem/*: policy + composition + recipes (dismiss/focus restore rules, roving/typeahead, shadcn recipes).
• apps/fret-ui-gallery: first-party exemplar/teaching surface; if the drift is “how should users author this in Fret?”, fix the snippet/page surface first.

If the change is “interaction policy” (dismiss rules, focus restore, keyboard nav rules), it almost never belongs in crates/fret-ui.

2) Pick the execution mode before you edit

Use this three-mode rule:

• Fast
  • Use when the task is trivial, local, and does not change a repo-level invariant.
  • Typical examples: wording/docs cleanup, a narrow obvious fix, small refactors that stay inside one surface and do not need state tracking.
  • Leave a concise proof in the final response or commit notes, but do not create workstream state just to justify a tiny change.
• Quick slice
  • Default for most non-trivial engineering work.
  • Use when one bounded slice can land with one smallest repro, one gate, and one evidence set, without needing a new lane.
  • This is the normal mode for bug fixes, parity adjustments, focused refactors, and small framework evolution that is still easy to review in one pass.
• Workstream
  • Use when the task spans multiple slices/sessions, changes a hard-to-reverse contract, needs ADR/alignment updates, or must leave explicit continuation/closeout state.
  • When the lane already exists, use fret-workstream-lifecycle and reopen it with the assumptions-first pass before editing code.

Escalate mode instead of stretching the lower mode:

• Fast → Quick slice when the task needs a real regression artifact.
• Quick slice → Workstream when scope, handoff needs, or contract risk stop being obvious.

3) The deliverables 3-pack (Repro + Gate + Evidence)

Before choosing the exact gate, do a goal-backward pass:

• write 3-5 truths that must be true when the task is actually done,
• name the artifacts that must exist for each truth,
• name the wiring that must connect those artifacts,
• then choose the smallest repro/gate/evidence set that proves the truths rather than just the edits.

Do not treat “task completed” or “docs updated” as proof that the intended outcome exists.

Every non-trivial change should leave these three deliverables:

• Repro: a smallest runnable target (demo/gallery page) or a tools/diag-scripts/*.json script.
• Gate: at least one regression gate:
  • unit/integration test for deterministic logic, and/or
  • fretboard diag script for event sequences/state machines, and/or
  • perf gate/baseline when perf is the goal.
• Evidence: 1–3 evidence anchors (file paths + key functions/tests/scripts) so reviewers can verify quickly.
• Prefer the smallest deterministic proof:
  • geometry assertions or capture_layout_sidecar for layout ownership/size negotiation
  • capture_screenshot for visible chrome/clipping/focus rings
  • capture_bundle for interaction state machines and shareable run context

4) test_id conventions (automation stability)

Goal: scripts should select intent-level targets, not pixel coordinates.

• Put test_id at the highest stable semantic surface that survives refactors:
  • reusable component crates → recipe/component layer
  • first-party UI Gallery surfaces → snippet/page/driver seam used by diagnostics
• Use stable, namespaced ids (examples):
  • ui-gallery-command-palette-trigger
  • ui-gallery-select-trigger
  • ui-gallery-docking-tab-bar-drag-anchor
• Avoid using list indices as ids; use model ids or stable row/item keys.

5) Diag script conventions (reviewable and gate-friendly)

• Prefer schema v2 for new scripts.
• Prefer selectors by test_id.
• Name scripts so they can be used as a gate label:
  • ui-gallery-<surface>-<behavior>-<expectation>.json
  • docking-<scenario>-<expectation>.json
• Keep scripts minimal: one scenario, one or two assertions, at least one capture_bundle.
• When proving layout ownership or size negotiation, add capture_layout_sidecar before falling back to screenshots.
• For first-party component pages, prefer the canonical nested corpus under tools/diag-scripts/ui-gallery/<family>/.

6) Evidence discipline (make it reversible)

When you fix a tricky issue, record:

• exact command(s) used,
• output dir / bundle path(s),
• the smallest script/test added,
• the conclusion (“what changed” + “why it’s correct”).

7) Skill testing discipline (triggering + behavior)

When creating or refreshing a skill, run a small manual test set before calling it done:

• 2-3 positive trigger prompts:
  • an obvious phrasing,
  • a paraphrased phrasing,
  • a repo-specific phrasing when the skill is Fret-only
• 1-2 negative prompts that should not load the skill
• 1 functional path:
  • the skill's main workflow completes with the expected repo command / artifact / code change
• 1 failure path when applicable:
  • missing tool, missing repo-ref mirror, or unsupported platform leads to a bounded fallback instead of hand-wavy output

8) External app repos (framework users)

If you are using these skills outside the Fret mono-repo:

• Expect that repo-local commands (fretboard, tools/*, tools/diag-scripts/*) must be run from a Fret checkout.
• Keep a sibling clone or submodule so evidence anchors remain clickable.

See: fret-external-app-mode.

Definition of done (what to leave behind)

Minimum deliverables (3-pack):

• Repro: smallest runnable target or diag script.
• Gate: test/script/perf gate that fails before and passes after.
• Evidence: 1–3 anchors (paths/functions/tests) and a copy/pasteable command.

Evidence anchors

• Execution-mode selection note: references/execution-mode-selection.md
• Goal-backward verification note: references/goal-backward-verification.md
• Layering and contracts: docs/architecture.md, docs/runtime-contract-matrix.md
• Crate/layer usage map: docs/crate-usage-guide.md
• Canonical shadcn migration status: docs/shadcn-declarative-progress.md
• Upstream local-mirror policy: docs/repo-ref.md
• Diag scripts and workflows: tools/diag-scripts/, .agents/skills/fret-diag-workflow/SKILL.md
• UI Gallery exemplar + evidence note: .agents/skills/fret-shadcn-source-alignment/references/ui-gallery-exemplar-and-evidence.md
• UI Gallery authoring gates: apps/fret-ui-gallery/src/lib.rs
• UI Gallery geometry/test-id helpers: apps/fret-ui-gallery/src/driver/render_flow.rs
• Perf gates and baselines: tools/perf/, docs/workstreams/perf-baselines/ (see .agents/skills/fret-diag-workflow/SKILL.md)

Examples

• Example: add a new skill with a durable outcome
  • User says: "Turn this workflow into a repeatable skill."
  • Actions: define triggers, keep SKILL.md lean, move deep material into references, and leave the 3-pack (Repro + Gate + Evidence).
  • Result: a skill that is easy to load and hard to regress.

Common pitfalls

• Fixing policy mismatches by adding runtime knobs in crates/fret-ui.
• Leaving no gate behind (“works on my machine” regressions).
• Unstable selectors (test_id missing/duplicated), leading to flaky scripts.
• Writing long narratives instead of a small reproducible repro + gate + evidence anchors.

Troubleshooting

• Symptom: validate --strict fails.
  • Fix: ensure frontmatter has --- delimiters, name matches the folder, and required headings exist.
• Symptom: anchor checks fail in the mono-repo.
  • Fix: replace directory-only anchors with stable file paths.
• Symptom: a shared/meta skill points to repo-ref/ paths and becomes noisy in external repos.
  • Fix: keep repo-ref/ anchors for source-alignment skills only; when they are required, pair them with docs/repo-ref.md and state that the mirrors are optional local state.

Related skills

• fret-repo-orientation
• fret-diag-workflow
• fret-shadcn-source-alignment