From 04fc2949030adcdbbf2ea5311277d84b47486950 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 22 Mar 2026 10:04:56 -0700 Subject: [PATCH] chore: regenerate eng review SKILL.md files Co-Authored-By: Claude Opus 4.6 (1M context) --- .../skills/gstack-plan-eng-review/SKILL.md | 4 +- plan-eng-review/SKILL.md | 156 +++++++++--------- 2 files changed, 80 insertions(+), 80 deletions(-) diff --git a/.agents/skills/gstack-plan-eng-review/SKILL.md b/.agents/skills/gstack-plan-eng-review/SKILL.md index ecfa85b8..14b799ae 100644 --- a/.agents/skills/gstack-plan-eng-review/SKILL.md +++ b/.agents/skills/gstack-plan-eng-review/SKILL.md @@ -327,8 +327,6 @@ Before reviewing anything, answer these questions: If the complexity check triggers (8+ files or 2+ new classes/services), proactively recommend scope reduction via AskUserQuestion — explain what's overbuilt, propose a minimal version that achieves the core goal, and ask whether to reduce or proceed as-is. If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1. - - Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section. **Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully.** Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components. @@ -407,6 +405,8 @@ Evaluate: **STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. + + ## CRITICAL RULE — How to ask questions Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews: * **One issue = one AskUserQuestion call.** Never combine multiple issues into one question. diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index dcc17f46..e9fb7b13 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -337,6 +337,84 @@ Before reviewing anything, answer these questions: If the complexity check triggers (8+ files or 2+ new classes/services), proactively recommend scope reduction via AskUserQuestion — explain what's overbuilt, propose a minimal version that achieves the core goal, and ask whether to reduce or proceed as-is. If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1. +Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section. + +**Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully.** Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components. + +## Review Sections (after scope is agreed) + +### 1. Architecture review +Evaluate: +* Overall system design and component boundaries. +* Dependency graph and coupling concerns. +* Data flow patterns and potential bottlenecks. +* Scaling characteristics and single points of failure. +* Security architecture (auth, data access, API boundaries). +* Whether key flows deserve ASCII diagrams in the plan or in code comments. +* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it. + +**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. + +### 2. Code quality review +Evaluate: +* Code organization and module structure. +* DRY violations—be aggressive here. +* Error handling patterns and missing edge cases (call these out explicitly). +* Technical debt hotspots. +* Areas that are over-engineered or under-engineered relative to my preferences. +* Existing ASCII diagrams in touched files — are they still accurate after this change? + +**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. + +### 3. Test review +Make a diagram of all new UX, new data flow, new codepaths, and new branching if statements or outcomes. For each, note what is new about the features discussed in this branch and plan. Then, for each new item in the diagram, make sure there is a corresponding test. + +For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user. + +**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. + +### Test Plan Artifact + +After producing the test diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input (replacing the lossy git-diff heuristic): + +```bash +source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG +USER=$(whoami) +DATETIME=$(date +%Y%m%d-%H%M%S) +``` + +Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md`: + +```markdown +# Test Plan +Generated by /plan-eng-review on {date} +Branch: {branch} +Repo: {owner/repo} + +## Affected Pages/Routes +- {URL path} — {what to test and why} + +## Key Interactions to Verify +- {interaction description} on {page} + +## Edge Cases +- {edge case} on {page} + +## Critical Paths +- {end-to-end flow that must work} +``` + +This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details. + +### 4. Performance review +Evaluate: +* N+1 queries and database access patterns. +* Memory-usage concerns. +* Caching opportunities. +* Slow or high-complexity code paths. + +**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. + ## Outside Voice — Independent Plan Challenge (optional, recommended) After all review sections are complete, offer an independent second opinion from a @@ -456,84 +534,6 @@ SOURCE = "codex" if Codex ran, "claude" if subagent ran. --- -Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section. - -**Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully.** Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components. - -## Review Sections (after scope is agreed) - -### 1. Architecture review -Evaluate: -* Overall system design and component boundaries. -* Dependency graph and coupling concerns. -* Data flow patterns and potential bottlenecks. -* Scaling characteristics and single points of failure. -* Security architecture (auth, data access, API boundaries). -* Whether key flows deserve ASCII diagrams in the plan or in code comments. -* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it. - -**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. - -### 2. Code quality review -Evaluate: -* Code organization and module structure. -* DRY violations—be aggressive here. -* Error handling patterns and missing edge cases (call these out explicitly). -* Technical debt hotspots. -* Areas that are over-engineered or under-engineered relative to my preferences. -* Existing ASCII diagrams in touched files — are they still accurate after this change? - -**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. - -### 3. Test review -Make a diagram of all new UX, new data flow, new codepaths, and new branching if statements or outcomes. For each, note what is new about the features discussed in this branch and plan. Then, for each new item in the diagram, make sure there is a corresponding test. - -For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user. - -**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. - -### Test Plan Artifact - -After producing the test diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input (replacing the lossy git-diff heuristic): - -```bash -source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG -USER=$(whoami) -DATETIME=$(date +%Y%m%d-%H%M%S) -``` - -Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md`: - -```markdown -# Test Plan -Generated by /plan-eng-review on {date} -Branch: {branch} -Repo: {owner/repo} - -## Affected Pages/Routes -- {URL path} — {what to test and why} - -## Key Interactions to Verify -- {interaction description} on {page} - -## Edge Cases -- {edge case} on {page} - -## Critical Paths -- {end-to-end flow that must work} -``` - -This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details. - -### 4. Performance review -Evaluate: -* N+1 queries and database access patterns. -* Memory-usage concerns. -* Caching opportunities. -* Slow or high-complexity code paths. - -**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. - ## CRITICAL RULE — How to ask questions Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews: * **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.