mirror of
https://github.com/garrytan/gstack.git
synced 2026-08-30 01:40:38 +02:00
Merge branch 'main' into garrytan/team-supabase-store
Resolved conflicts across 23 files. Key merge decisions: - Adopted main's TemplateContext type in gen-skill-docs.ts - Adopted main's new features (trigger phrases, codex integration, analytics, proactive config, review chaining) - Replaced gstack-review-log/gstack-review-read helpers with inline approach using $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl paths - Added "commit":"COMMIT" field to all review log entries (from main) - Kept our $PROJECTS_DIR/$SLUG path reorganization throughout - Added Codex E2E test from main + our E2E isolation cleanup Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -4,7 +4,10 @@ version: 1.0.0
|
||||
description: |
|
||||
Eng manager-mode plan review. Lock in the execution plan — architecture,
|
||||
data flow, diagrams, edge cases, test coverage, performance. Walks through
|
||||
issues interactively with opinionated recommendations.
|
||||
issues interactively with opinionated recommendations. Use when asked to
|
||||
"review the architecture", "engineering review", or "lock in the plan".
|
||||
Proactively suggest when the user has a plan or design doc and is about to
|
||||
start coding — to catch architecture issues before implementation.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
@@ -60,6 +63,16 @@ When evaluating architecture, think "boring by default." When reviewing tests, t
|
||||
|
||||
## BEFORE YOU START:
|
||||
|
||||
### Design Doc Check
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
|
||||
DESIGN=$(ls -t $PROJECTS_DIR/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
[ -z "$DESIGN" ] && DESIGN=$(ls -t $PROJECTS_DIR/$SLUG/*-design-*.md 2>/dev/null | head -1)
|
||||
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
|
||||
```
|
||||
If a design doc exists, read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design — check the prior version for context on what changed and why.
|
||||
|
||||
### Step 0: Scope Challenge
|
||||
Before reviewing anything, answer these questions:
|
||||
1. **What existing code already partially or fully solves each sub-problem?** Can we capture outputs from existing flows rather than building parallel ones?
|
||||
@@ -71,6 +84,29 @@ 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.
|
||||
|
||||
### Step 0.5: Codex plan review (optional)
|
||||
|
||||
Check if the Codex CLI is available: `which codex 2>/dev/null`
|
||||
|
||||
If available, after presenting Step 0 findings, use AskUserQuestion:
|
||||
```
|
||||
Want an independent Codex (OpenAI) review of this plan before the detailed review?
|
||||
A) Yes — let Codex critique the plan independently
|
||||
B) No — proceed with the Claude review only
|
||||
```
|
||||
|
||||
If the user chooses A: tell Codex to read the plan file itself (avoids ARG_MAX limits for large plans):
|
||||
```bash
|
||||
codex exec "You are a brutally honest technical reviewer. Read the plan file at <plan-file-path> and review it for: logical gaps and unstated assumptions, missing error handling or edge cases, overcomplexity (is there a simpler approach?), feasibility risks (what could go wrong?), and missing dependencies or sequencing issues. Be direct. Be terse. No compliments. Just the problems." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached
|
||||
```
|
||||
|
||||
Replace `<plan-file-path>` with the actual path to the plan file detected earlier. Codex has filesystem access in read-only mode and will read the file itself.
|
||||
|
||||
Present the full output under a `CODEX SAYS (plan review):` header. Note any concerns
|
||||
that should inform the subsequent engineering review sections.
|
||||
|
||||
If Codex is not available, skip silently.
|
||||
|
||||
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.
|
||||
@@ -101,7 +137,7 @@ 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.
|
||||
|
||||
### 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 JS or Rails test.
|
||||
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.
|
||||
|
||||
@@ -111,23 +147,15 @@ For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in C
|
||||
|
||||
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):
|
||||
|
||||
{{ARTIFACT_SETUP}}
|
||||
|
||||
```bash
|
||||
mkdir -p $PROJECTS_DIR/$SLUG/plans
|
||||
FILE="$PROJECTS_DIR/$SLUG/plans/$DATE-$BRANCH-test-plan.md"
|
||||
[ -f "$FILE" ] && FILE="$PROJECTS_DIR/$SLUG/plans/$DATE-$(date +%H%M)-$BRANCH-test-plan.md"
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p $PROJECTS_DIR/$SLUG
|
||||
USER=$(whoami)
|
||||
DATETIME=$(date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
Write to the file path resolved above with this content (include the YAML frontmatter):
|
||||
Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: test-plan
|
||||
branch: {branch}
|
||||
date: {YYYY-MM-DD}
|
||||
skill: plan-eng-review
|
||||
---
|
||||
# Test Plan
|
||||
Generated by /plan-eng-review on {date}
|
||||
Branch: {branch}
|
||||
@@ -148,11 +176,6 @@ Repo: {owner/repo}
|
||||
|
||||
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.
|
||||
|
||||
After writing the test plan, register it in the manifest:
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-manifest-append test-plan "plans/$(basename "$FILE")" plan-eng-review "$BRANCH"
|
||||
```
|
||||
|
||||
### 4. Performance review
|
||||
Evaluate:
|
||||
* N+1 queries and database access patterns.
|
||||
@@ -235,7 +258,7 @@ After producing the Completion Summary above, persist the review result:
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
mkdir -p $PROJECTS_DIR/$SLUG/reviews
|
||||
echo '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl
|
||||
echo '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","commit":"COMMIT"}' >> $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl
|
||||
```
|
||||
|
||||
Substitute values from the Completion Summary:
|
||||
@@ -244,8 +267,26 @@ Substitute values from the Completion Summary:
|
||||
- **unresolved**: number from "Unresolved decisions" count
|
||||
- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
|
||||
- **MODE**: FULL_REVIEW / SCOPE_REDUCED
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
{{REVIEW_DASHBOARD}}
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
|
||||
|
||||
**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
|
||||
|
||||
**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
|
||||
|
||||
**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
|
||||
|
||||
Use AskUserQuestion with only the applicable options:
|
||||
- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
|
||||
- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
|
||||
- **C)** Ready to implement — run /ship when done
|
||||
|
||||
## Unresolved decisions
|
||||
If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
|
||||
|
||||
Reference in New Issue
Block a user