diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index ad983d4e..a46d55e2 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -159,6 +159,25 @@ ATTEMPTED: [what you tried] RECOMMENDATION: [what the user should do next] ``` +## SETUP (run this check BEFORE any browse command) + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) +B="" +[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse" +[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse +if [ -x "$B" ]; then + echo "READY: $B" +else + echo "NEEDS_SETUP" +fi +``` + +If `NEEDS_SETUP`: +1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait. +2. Run: `cd && ./setup` +3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash` + # YC Office Hours You are a **YC office hours partner**. Your job is to ensure the problem is understood before solutions are proposed. You adapt to what the user is building — startup founders get the hard questions, builders get an enthusiastic collaborator. This skill produces design docs, not code. @@ -423,6 +442,66 @@ Present via AskUserQuestion. Do NOT proceed without user approval of the approac --- +## Visual Sketch (UI ideas only) + +If the chosen approach involves user-facing UI (screens, pages, forms, dashboards, +or interactive elements), generate a rough wireframe to help the user visualize it. +If the idea is backend-only, infrastructure, or has no UI component — skip this +section silently. + +**Step 1: Gather design context** + +1. Check if `DESIGN.md` exists in the repo root. If it does, read it for design + system constraints (colors, typography, spacing, component patterns). Use these + constraints in the wireframe. +2. Apply core design principles: + - **Information hierarchy** — what does the user see first, second, third? + - **Interaction states** — loading, empty, error, success, partial + - **Edge case paranoia** — what if the name is 47 chars? Zero results? Network fails? + - **Subtraction default** — "as little design as possible" (Rams). Every element earns its pixels. + - **Design for trust** — every interface element builds or erodes user trust. + +**Step 2: Generate wireframe HTML** + +Generate a single-page HTML file with these constraints: +- **Intentionally rough aesthetic** — use system fonts, thin gray borders, no color, + hand-drawn-style elements. This is a sketch, not a polished mockup. +- Self-contained — no external dependencies, no CDN links, inline CSS only +- Show the core interaction flow (1-3 screens/states max) +- Include realistic placeholder content (not "Lorem ipsum" — use content that + matches the actual use case) +- Add HTML comments explaining design decisions + +Write to a temp file: +```bash +SKETCH_FILE="/tmp/gstack-sketch-$(date +%s).html" +``` + +**Step 3: Render and capture** + +```bash +$B goto "file://$SKETCH_FILE" +$B screenshot /tmp/gstack-sketch.png +``` + +If `$B` is not available (browse binary not set up), skip the render step. Tell the +user: "Visual sketch requires the browse binary. Run the setup script to enable it." + +**Step 4: Present and iterate** + +Show the screenshot to the user. Ask: "Does this feel right? Want to iterate on the layout?" + +If they want changes, regenerate the HTML with their feedback and re-render. +If they approve or say "good enough," proceed. + +**Step 5: Include in design doc** + +Reference the wireframe screenshot in the design doc's "Recommended Approach" section. +The screenshot file at `/tmp/gstack-sketch.png` can be referenced by downstream skills +(`/plan-design-review`, `/design-review`) to see what was originally envisioned. + +--- + ## Phase 4.5: Founder Signal Synthesis Before writing the design doc, synthesize the founder signals you observed during the session. These will appear in the design doc ("What I noticed") and in the closing conversation (Phase 6). @@ -559,7 +638,73 @@ Supersedes: {prior filename — omit this line if first design on this branch} {observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.} ``` -Present the design doc to the user via AskUserQuestion: +--- + +## Spec Review Loop + +Before presenting the document to the user for approval, run an adversarial review. + +**Step 1: Dispatch reviewer subagent** + +Use the Agent tool to dispatch an independent reviewer. The reviewer has fresh context +and cannot see the brainstorming conversation — only the document. This ensures genuine +adversarial independence. + +Prompt the subagent with: +- The file path of the document just written +- "Read this document and review it on 5 dimensions. For each dimension, note PASS or + list specific issues with suggested fixes. At the end, output a quality score (1-10) + across all dimensions." + +**Dimensions:** +1. **Completeness** — Are all requirements addressed? Missing edge cases? +2. **Consistency** — Do parts of the document agree with each other? Contradictions? +3. **Clarity** — Could an engineer implement this without asking questions? Ambiguous language? +4. **Scope** — Does the document creep beyond the original problem? YAGNI violations? +5. **Feasibility** — Can this actually be built with the stated approach? Hidden complexity? + +The subagent should return: +- A quality score (1-10) +- PASS if no issues, or a numbered list of issues with dimension, description, and fix + +**Step 2: Fix and re-dispatch** + +If the reviewer returns issues: +1. Fix each issue in the document on disk (use Edit tool) +2. Re-dispatch the reviewer subagent with the updated document +3. Maximum 3 iterations total + +**Convergence guard:** If the reviewer returns the same issues on consecutive iterations +(the fix didn't resolve them or the reviewer disagrees with the fix), stop the loop +and persist those issues as "Reviewer Concerns" in the document rather than looping +further. + +If the subagent fails, times out, or is unavailable — skip the review loop entirely. +Tell the user: "Spec review unavailable — presenting unreviewed doc." The document is +already written to disk; the review is a quality bonus, not a gate. + +**Step 3: Report and persist metrics** + +After the loop completes (PASS, max iterations, or convergence guard): + +1. Tell the user the result — summary by default: + "Your doc survived N rounds of adversarial review. M issues caught and fixed. + Quality score: X/10." + If they ask "what did the reviewer find?", show the full reviewer output. + +2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns" + section to the document listing each unresolved issue. Downstream skills will see this. + +3. Append metrics: +```bash +mkdir -p ~/.gstack/analytics +echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> ~/.gstack/analytics/spec-review.jsonl 2>/dev/null || true +``` +Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review. + +--- + +Present the reviewed design doc to the user via AskUserQuestion: - A) Approve — mark Status: APPROVED and proceed to handoff - B) Revise — specify which sections need changes (loop back to revise those sections) - C) Start over — return to Phase 2 diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index caf91acb..e0ff98a7 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -23,6 +23,8 @@ allowed-tools: {{PREAMBLE}} +{{BROWSE_SETUP}} + # YC Office Hours You are a **YC office hours partner**. Your job is to ensure the problem is understood before solutions are proposed. You adapt to what the user is building — startup founders get the hard questions, builders get an enthusiastic collaborator. This skill produces design docs, not code. @@ -287,6 +289,10 @@ Present via AskUserQuestion. Do NOT proceed without user approval of the approac --- +{{DESIGN_SKETCH}} + +--- + ## Phase 4.5: Founder Signal Synthesis Before writing the design doc, synthesize the founder signals you observed during the session. These will appear in the design doc ("What I noticed") and in the closing conversation (Phase 6). @@ -423,7 +429,13 @@ Supersedes: {prior filename — omit this line if first design on this branch} {observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.} ``` -Present the design doc to the user via AskUserQuestion: +--- + +{{SPEC_REVIEW_LOOP}} + +--- + +Present the reviewed design doc to the user via AskUserQuestion: - A) Approve — mark Status: APPROVED and proceed to handoff - B) Revise — specify which sections need changes (loop back to revise those sections) - C) Start over — return to Phase 2