From ec4ef861d5cd3b8facbffa90cc5be675c6b1d7b6 Mon Sep 17 00:00:00 2001 From: Malik Salim Date: Tue, 31 Mar 2026 04:39:46 -0400 Subject: [PATCH] fix: prefer repo-local design docs in plan reviews --- autoplan/SKILL.md | 10 ++++++++-- plan-ceo-review/SKILL.md | 22 +++++++++++++++++----- plan-ceo-review/SKILL.md.tmpl | 12 +++++++++--- plan-eng-review/SKILL.md | 22 +++++++++++++++++----- plan-eng-review/SKILL.md.tmpl | 12 +++++++++--- scripts/resolvers/review.ts | 10 ++++++++-- test/gen-skill-docs.test.ts | 12 ++++++++++++ 7 files changed, 80 insertions(+), 20 deletions(-) diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 31ae9ab21..a3eae9e8d 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -517,8 +517,14 @@ After /office-hours completes, re-run the design doc check: setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 48a8ab409..b789e592b 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -549,11 +549,17 @@ Then read CLAUDE.md, TODOS.md, and any existing architecture docs. setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` -If a design doc exists (from `/office-hours`), 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. +If a design doc exists, read it. Prefer repo-local `DESIGN.md` or `design-system.md` when present — that is the best signal for the current subproject in a monorepo. Otherwise, fall back to the most relevant `~/.gstack/projects/$SLUG/*-design-*.md` document from `/office-hours`. Use the selected document 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. **Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above): ```bash @@ -620,8 +626,14 @@ After /office-hours completes, re-run the design doc check: setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index b33aaa30c..7fbc7accf 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -108,11 +108,17 @@ Then read CLAUDE.md, TODOS.md, and any existing architecture docs. setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` -If a design doc exists (from `/office-hours`), 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. +If a design doc exists, read it. Prefer repo-local `DESIGN.md` or `design-system.md` when present — that is the best signal for the current subproject in a monorepo. Otherwise, fall back to the most relevant `~/.gstack/projects/$SLUG/*-design-*.md` document from `/office-hours`. Use the selected document 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. **Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above): ```bash diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index d2715aac0..a5bc7b8bf 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -475,11 +475,17 @@ When evaluating architecture, think "boring by default." When reviewing tests, t setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -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. +If a design doc exists, read it. Prefer repo-local `DESIGN.md` or `design-system.md` when present — that is the best signal for the current subproject in a monorepo. Otherwise, fall back to the most relevant `~/.gstack/projects/$SLUG/*-design-*.md` document from `/office-hours`. Use the selected document 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. ## Prerequisite Skill Offer @@ -530,8 +536,14 @@ After /office-hours completes, re-run the design doc check: setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index f15fc7f58..01c1d9eed 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -71,11 +71,17 @@ When evaluating architecture, think "boring by default." When reviewing tests, t setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -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. +If a design doc exists, read it. Prefer repo-local `DESIGN.md` or `design-system.md` when present — that is the best signal for the current subproject in a monorepo. Otherwise, fall back to the most relevant `~/.gstack/projects/$SLUG/*-design-*.md` document from `/office-hours`. Use the selected document 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. {{BENEFITS_FROM}} diff --git a/scripts/resolvers/review.ts b/scripts/resolvers/review.ts index de01698a3..786c6c8a9 100644 --- a/scripts/resolvers/review.ts +++ b/scripts/resolvers/review.ts @@ -243,8 +243,14 @@ After /${first} completes, re-run the design doc check: setopt +o nomatch 2>/dev/null || true # zsh compat 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 ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) -[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +if [ -f DESIGN.md ]; then + DESIGN="$PWD/DESIGN.md" +elif [ -f design-system.md ]; then + DESIGN="$PWD/design-system.md" +else + DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) + [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +fi [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" \`\`\` diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index fff58a5e7..cc02cb7f4 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1197,6 +1197,18 @@ describe('BENEFITS_FROM resolver', () => { expect(engContent).toContain('skipping these sections'); expect(ceoContent).toContain('Follow its instructions from top to bottom'); }); + + test('plan reviews prefer repo-local design docs before ~/.gstack history', () => { + expect(ceoContent).toContain('if [ -f DESIGN.md ]; then'); + expect(ceoContent).toContain('DESIGN="$PWD/DESIGN.md"'); + expect(ceoContent).toContain('design-system.md'); + expect(ceoContent).toContain('~/.gstack/projects/$SLUG'); + + expect(engContent).toContain('if [ -f DESIGN.md ]; then'); + expect(engContent).toContain('DESIGN="$PWD/DESIGN.md"'); + expect(engContent).toContain('design-system.md'); + expect(engContent).toContain('~/.gstack/projects/$SLUG'); + }); }); // --- {{INVOKE_SKILL}} resolver tests ---