agentleFS
ChariereFiedlerChariereFiedler/ronce-racine/skills/frontend-spec-call-site-audit/SKILL.md

frontend-spec-call-site-audit

Skill9 starsChanged 25 days agoMITView on GitHub

Use BEFORE writing any frontend feature ticket or spec - new page, new component, new dashboard section, "add an X page", "ajoute une page X". Use when drafting acceptance criteria for a UI change in an existing app.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    This skill: when: drafting a frontend ticket/spec or acceptance criteria for a page/component in an existing app

    line 16
  2. Very specific:

    refactoring-shared-component-api: instead if: changing the API of an already-shipped component (props/emits/slots) with no new ticket

    line 17
  3. Distinctive:

    writing-robust-tests: instead if: the feature is coded and needs coverage

    line 18
  4. Distinctive:

    Read a neighbouring page already specced and copy its conventions (empty states, breadcrumbs, i18n) before inventing

    line 29
  5. Distinctive:

    Global navigation: do the sidebar / creation menu ("+ New") need to gain or change an entry?

    line 36
  6. Very specific:

    Test procedure: scripts/audit-entry-points.test.ts - deterministic behavioral test of the script (positive + negative fixture).

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Codebase audit before a frontend spec

If the current repo has a specific spec skill, it wins.

This skill vs. others

  • This skill when: drafting a frontend ticket/spec or acceptance criteria for a page/component in an existing app
  • refactoring-shared-component-api instead if: changing the API of an already-shipped component (props/emits/slots) with no new ticket
  • writing-robust-tests instead if: the feature is coded and needs coverage

Principle

A frontend ticket never describes a component in a vacuum. Every page/component lives in a graph: side navigation, global menus ("+ New"), breadcrumbs, parent pages, incoming links. Specifying without mapping that graph = shipping an isolated feature and breaking the adjacent call sites (orphaned component, menu that no longer routes, missing creation entry).

Refuse to draft the acceptance criteria until the audit is done.

Context to gather (before acting)

  • Router + navigation files: read the route config, the sidebar/header/global menu to know where an entry gets added
  • Read a neighbouring page already specced and copy its conventions (empty states, breadcrumbs, i18n) before inventing
  • Data scope: global / per organization / per project - determines where the page lives and which menus are affected

Audit checklist - to paste into the ticket

  1. Call sites of the main component: grep the frontend code; list every page/component that uses it
  2. Routes / incoming links: grep the target route; who points at it (sidebar, header, breadcrumb, links)?
  3. Global navigation: do the sidebar / creation menu ("+ New") need to gain or change an entry?
  4. Data scope: is the entity global, per organization, per project? (determines where the page lives and which menus are affected)
  5. UX edge cases enumerated:
    • 0 entities → empty state with message + CTA
    • 1 entity → does the visualization hold up? (no giant canvas for a single node)
    • N entities → pagination/scroll, responsive layout
    • Backend error → display + retry · Loading → skeleton/spinner
  6. i18n: required keys listed (or "not applicable" justified)

Acceptance criteria: flows, not isolated actions

At least 1 scenario expressed as a complete user flow:

  • "How do you create an X from any page?"
  • "When the app has 0 / 1 / N entities, what does the page look like?"
  • "The user goes back: what is preserved (URL, scroll, filters)?"

A scenario like "I click the card → I see the detail" says nothing about the sidebar, the creation menu, or the other pages that display the same card.

Traps & rationalizations

ExcuseReality
"The component is isolated, no need to audit call sites"No component is isolated: sidebar, creation menu and breadcrumb point at it. Grep first.
"The ticket already describes clicking the card → detail"An isolated action says nothing about global navigation or the other pages showing the same card. Full flow required.
"I'll write the criteria, we'll audit at implementation"Broken call sites are found in prod. The audit is blocking before the criteria.
"0/1/N entities, the default UX will do"The empty state and the single-node case are the most frequent regressions. Enumerated or not shipped.

Exit condition

  • Audit of the 6 points complete, grep results cited in the ticket (call sites, incoming links, global navigation)
  • At least 1 criterion expressed as a complete user flow
  • Edge cases 0 / 1 / N + error + loading enumerated
  • i18n keys listed or "not applicable" justified
  • No acceptance criteria drafted before the audit

Tooling

  • Test procedure: scripts/audit-entry-points.test.ts - deterministic behavioral test of the script (positive + negative fixture). Run npx tsx scripts/audit-entry-points.test.ts from the canonical repo after any change to the script (also picked up by npm test). Not distributed to target repos.
  • scripts/audit-entry-points.ts <ComponentName|-> <route|-> [rootDir] - pre-fills the audit: call sites, incoming links to the route, navigation files (sidebar/header/menu) to check
  • templates/ticket-frontend.md - ticket skeleton with the blocking audit section

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.