mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +00:00

cleanup(engineering): address remaining 7 polish items from PR #718 bot review

Bundle of low-medium-severity follow-ups that were deferred when PR #720
landed the 3 blocking bugs. None of these silently break correctness —
they're discoverability, consistency, and convention gaps.

Bugs / code-quality:

1. fullstack_decision_engine.py: asymmetric cadence matching
   `inputs.cadence in target or target in inputs.cadence` produced
   asymmetric results — "per-pr" matched "per-pr-with-gates" but not
   vice versa. Profile cadences are intentional alternatives joined
   by "-or-" (e.g. "weekly-or-on-demand" → {weekly, on-demand}); now
   parsed explicitly with "-with-..." modifier suffixes stripped.

   Verified:
     cadence=per-pr → matches per-pr, per-pr-with-gates, daily-or-per-pr
     cadence=daily  → matches daily-or-per-pr (only)
     cadence=on-demand → matches weekly-or-on-demand

2. fullstack_decision_engine.py: rename weight_total/weight_matched
   to w_total/w_matched. Backend and frontend engines already use the
   short form; this aligns the three files as a family.

3. sync-gemini-skills.py: 3-way name collision in dedup logic
   The naive `if name in seen_names: name = parent-name` handled one
   collision but not two. Three "status" skills under "skills" parent
   dirs produced two entries both named "skills-status". Now suffixes
   with -2, -3, ... so each entry has a unique index name. Eliminates
   the duplicate-name ambiguity surfaced when checking PR #713.

Discoverability:

4. senior-fullstack/SKILL.md: surface fullstack_decision_engine.py in
   the labeled "Tools" section at the top. Previously only mentioned
   inline in the body (5 references buried in the Stack Decision Matrix
   section); not findable when scanning the SKILL.md.

Conventions / v2.8.0 compliance:

5. commands/cs-{fullstack,backend,frontend}-review.md: add explicit
   "## Forcing-question library" section header per the v2.8.0
   convention. Each lists the 7 questions inline with a pointer to
   the canonical reference file.

6. agents/engineering/cs-{fullstack,backend,frontend}-engineer.md:
   alphabetize the specialist list in the description field (annotated
   that workflow body order remains dependency-driven). Makes the
   three agent descriptions consistent as a family.

7. agents/engineering/cs-{backend,frontend}-engineer.md: promote the
   "Cross-agent invocation" content out of Workflow 3 into a dedicated
   "## When invoked as fork target" section with an explicit question-
   skip table per parent agent (cs-fullstack-engineer, cs-cto-advisor,
   cs-vpe-advisor, cs-ciso-advisor for backend; cs-fullstack-engineer,
   cs-content-creator, cs-product-manager for frontend). Closes the
   cross-agent contract gap the bot flagged.

Not changed:

- CLAUDE.md plugin-schema section (already corrected in #715; bot's
  "stale text" claim was incorrect — it was reading the cumulative diff)
- Workflow body specialist order (intentional dependency order; would
  break the SLO-first → API → DB → migration → observability sequence)

Verification:
- All 3 decision engines: --sample → exit 0
- Cadence matching: 3 test cases pass cleanly
- check_plugin_json.py --all → 0 FAIL, 0 WARN, 69 OK
- sync-gemini-skills.py → 392 unique names (was 391 unique / 1 dupe)

2026-05-21 13:47:08 +00:00

3.2 KiB

Raw Permalink Blame History

description	argument-hint
Frontend engineering review — walks the 7 Matt Pocock forcing questions (device, LCP target, rendering, bundle budget, SEO vs auth, design system, WCAG), picks the framework + rendering profile, forks into specialists (a11y-audit, performance-profiler, epic-design). Invokes the cs-frontend-engineer agent with context fork.	<problem or surface to review>

/cs:frontend-review — Frontend engineering review

Use the cs-frontend-engineer agent (uses context: fork) to handle this inquiry:

$ARGUMENTS

Forcing-question library

Canonical source: engineering-team/skills/senior-frontend/references/forcing_questions.md (7 questions, one-per-turn, recommendation + canon citation per question).

Primary device + network (desktop-fiber / mobile-4G / low-end Android / corporate)
LCP target on primary device (milliseconds)
Server Components vs SPA vs SSR vs SSG
JS bundle budget per route (KB gzipped)
SEO-dependent or auth-walled
Design-system location (Figma + tokens / ad-hoc Tailwind / headless UI)
WCAG target (AA / AAA / best-effort) + accessibility owner

Routing protocol

Walk the 7 forcing questions in engineering-team/skills/senior-frontend/references/forcing_questions.md. One per turn. Recommend with cited canon. Track in /tmp/frontend-grill-<date>.md.
Surface kill criteria — e.g., "SEO-dependent + SPA-only" trips. STOP and resolve.

Run the deterministic profile picker:

python engineering-team/skills/senior-frontend/scripts/frontend_decision_engine.py \
  --primary-device <mobile-4g|desktop-fiber|low-end-android|corporate-network> \
  --lcp-target-ms <N> --seo-dependent <true|false> \
  --auth-walled <true|false> --team-size <N>

Surface the matched profile + runner-up tradeoff (if within 15%).
Fork into specialists (one at a time, depth-first):
- a11y-audit for WCAG baseline (always)
- performance-profiler for CWV baseline + bundle audit
- epic-design only for astro-or-static marketing surfaces
- apple-hig-expert only for Apple-platform-native surfaces
- dependency-auditor before any major release
- cs-karpathy-reviewer before any commit

Output expectations (≤ 200-word digest)

Matched profile + reason
Three CWV targets (LCP, INP, CLS) at p75 on the primary device
Per-route JS bundle budget in KB-gzip
Named a11y owner
List of specialists invoked + artifact paths
Recommended next sub-skill

Anti-patterns

❌ Recommending Next App Router as a universal default. Device + SEO + auth decide rendering.
❌ Setting "fast" as a target. Pick a number in ms.
❌ Skipping a11y-audit on customer-facing surface.
❌ Reimplementing perf-profiling logic. Fork into performance-profiler.

Customization

Profiles live at engineering-team/skills/senior-frontend/profiles/. Four built-in: next-app-router, remix-or-sveltekit, vite-spa, astro-or-static. Copy one to <your-org>.json and adjust to add your org's defaults.

/cs:fullstack-review — full-stack lens (parent)
/cs:backend-review — for API contract on the consumer side
/cs:engineer-grill — cross-role 21-question grill
/karpathy-check — Karpathy 4-principle review

3.2 KiB Raw Permalink Blame History