mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-11 22:51:28 +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
Fullstack engineering review — walks the 7 Matt Pocock forcing questions, picks the profile, forks into POWERFUL specialists (api-design-reviewer, database-designer, slo-architect). Invokes the cs-fullstack-engineer agent with context fork.	<problem or codebase to review>

/cs:fullstack-review — Fullstack engineering review

Use the cs-fullstack-engineer agent (which uses context: fork to keep the parent thread clean) to handle this inquiry:

$ARGUMENTS

Forcing-question library

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

Team size now + 12-month headcount
Deployment cadence (per-PR / daily / weekly / quarterly)
Customer-facing / internal tool / marketing site
One-year p50 + p99 traffic forecast
Hiring-against vs training-into the stack
Year-one monthly cloud + SaaS budget ceiling
Three verifiable success criteria with numeric targets

Routing protocol

Walk the 7 forcing questions in engineering-team/skills/senior-fullstack/references/forcing_questions.md. One per turn. Recommend the answer with cited canon. Track in /tmp/fullstack-grill-<date>.md.
Surface kill criteria — if any question trips one (e.g., "microservices day 1, team size 3"), STOP and resolve before proceeding.

Run the deterministic profile picker:

python engineering-team/skills/senior-fullstack/scripts/fullstack_decision_engine.py \
  --team-size <N> --team-size-12mo <N12> --cadence <c> \
  --user-facing <true|false> --budget <USD/mo> \
  --traffic-p99-rps <N> --data-sensitivity <tier>

Surface the matched profile + runner-up tradeoff (if within 15%).
Fork into specialists (one at a time, depth-first):
- api-design-reviewer for API contract
- database-designer for schema
- slo-architect for reliability target
- ci-cd-pipeline-builder for the pipeline
- performance-profiler for perf baseline
- cs-karpathy-reviewer before any commit

Output expectations (≤ 200-word digest)

Matched profile + reason
Three verifiable success criteria with numeric targets
Named approver chain
List of specialists invoked + artifact paths
Recommended next sub-skill (if any)

Anti-patterns

❌ Bundling forcing questions — one per turn.
❌ Skipping the kill-criteria check.
❌ Reimplementing specialist scope. Fork — don't duplicate.
❌ Auto-approving production changes. Always name the human approver.

Customization

Profiles live at engineering-team/skills/senior-fullstack/profiles/. To customize for your org:

Copy saas-startup.json (or whichever best fits) to <your-org>.json.
Edit constraints, stack_recommendations, success_thresholds, named_approver_chain.
The decision engine auto-discovers new profile JSONs.

/cs:frontend-review — frontend-only deep dive
/cs:backend-review — backend-only deep dive
/cs:engineer-grill — cross-role 21-question forcing-question runner
/karpathy-check — Karpathy 4-principle review before commit

3.2 KiB Raw Permalink Blame History