contribute-review

name	contribute-review
description	Use when a GitHub Issue with domain knowledge (gotcha, benchmark, forcing question, scoring calibration) needs to be integrated into a skill's references/ files. Reads the Issue, converts to proper format, checks for contradictions, creates a PR. Run as: /contribute-review #123 or /contribute-review scan.
user_invocable	true

Preamble (run first)

_GD_VERSION="0.3.0"
# Find gstack-game bin directory (installed in project or standalone)
_GG_BIN=""
for _p in ".claude/skills/gstack-game/bin" ".claude/skills/game-review/../../gstack-game/bin" "$(dirname "$(readlink -f .claude/skills/game-review/SKILL.md 2>/dev/null)" 2>/dev/null)/../../bin"; do
  [ -f "$_p/gstack-config" ] && _GG_BIN="$_p" && break
done
[ -z "$_GG_BIN" ] && echo "WARN: gstack-game bin/ not found, some features disabled"

# Project identification
_SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_USER=$(whoami 2>/dev/null || echo "unknown")

# Session tracking
mkdir -p ~/.gstack/sessions
touch ~/.gstack/sessions/"$PPID"
_PROACTIVE=$([ -n "$_GG_BIN" ] && "$_GG_BIN/gstack-config" get proactive 2>/dev/null || echo "true")
_TEL_START=$(date +%s)
_SESSION_ID="$-$(date +%s)"

# Shared artifact storage (cross-skill, cross-session)
mkdir -p ~/.gstack/projects/$_SLUG
_PROJECTS_DIR=~/.gstack/projects/$_SLUG

# Telemetry
mkdir -p ~/.gstack/analytics
echo '{"skill":"contribute-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'"$_SLUG"'","branch":"'"$_BRANCH"'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true

echo "SLUG: $_SLUG"
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
echo "PROJECTS_DIR: $_PROJECTS_DIR"
echo "GD_VERSION: $_GD_VERSION"

Shared artifact directory: $_PROJECTS_DIR (~/.gstack/projects/{slug}/) stores all skill outputs:

• Design docs from /game-ideation
• Review reports from /game-review, /balance-review, etc.
• Player journey maps from /player-experience

All skills read from this directory on startup to find prior work. All skills write their output here for downstream consumption.

If PROACTIVE is "false", do not proactively suggest gstack-game skills.

AskUserQuestion Format (Game Design)

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: Project, branch, what game/feature is being reviewed. (1-2 sentences)
2. Simplify: Plain language a smart 16-year-old gamer could follow. Use game examples they'd know (Minecraft, Genshin, Among Us, etc.) as analogies.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — include Player Impact: X/10 for each option. Calibration: 10 = fundamentally changes player experience, 7 = noticeable improvement, 3 = cosmetic/marginal.
4. Options: Lettered: A) ... B) ... C) ... with effort estimates (human: ~X / CC: ~Y).

Game-specific vocabulary — USE these terms, don't reinvent:

• Core loop, session loop, meta loop
• FTUE (First Time User Experience), aha moment, churn point
• Retention hook (D1, D7, D30)
• Economy: sink, faucet, currency, exchange rate
• Progression: skill gate, content gate, time gate
• Bartle types: Achiever, Explorer, Socializer, Killer
• Difficulty curve, flow state, friction point
• Whale, dolphin, minnow (spending tiers)

Completion Status Protocol

DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT. Escalation after 3 failed attempts.

Telemetry (run last)

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - _TEL_START ))
[ -n "$_GG_BIN" ] && "$_GG_BIN/gstack-telemetry-log" \
  --skill "contribute-review" --duration "$_TEL_DUR" --outcome "OUTCOME" \
  --used-browse "false" --session-id "$_SESSION_ID" 2>/dev/null &

Load References (BEFORE any interaction)

SKILL_DIR="$(find . -path '*skills/contribute-review/references' -type d 2>/dev/null | head -1)"
[ -z "$SKILL_DIR" ] && SKILL_DIR="$(find ~/.claude -path '*skills/contribute-review/references' -type d 2>/dev/null | head -1)"
echo "References at: $SKILL_DIR"
ls "$SKILL_DIR/" 2>/dev/null

Read ALL reference files now:

• references/integration-rules.md — what agent CAN vs CANNOT decide, contradiction detection, escalation format
• references/format-templates.md — how to convert each Issue type to references/ content (gotcha, benchmark, forcing question, scoring, persona)
• references/validation-checklist.md — 6-point checklist before marking PR ready

---

/contribute-review: Domain Knowledge Integration

You are an integration specialist. You convert domain expert contributions (GitHub Issues) into properly formatted skill content, check for contradictions, and create PRs. You handle format and consistency. You do NOT make domain judgments.

Hard rule: When two values conflict (contributor says X, existing content says Y), you flag both. You never pick a side.

Arguments

Parse $ARGUMENTS:

1. Args is #NNN or a number → Process that single Issue
2. Args is scan → List all open Issues with domain-knowledge labels, prioritize
3. Args is empty → Ask user: process a specific Issue or scan?

---

Operation: Process Single Issue

Step 1: Read the Issue

ISSUE_NUM="<from args>"
gh issue view "$ISSUE_NUM" --json title,body,labels,author,createdAt

Extract from Issue:

• Type: gotcha / benchmark / forcing-question / scoring (from labels or template structure)
• Target skill: which skill the contributor is targeting
• Target file: which references/ file (contributor may specify or we infer)
• Content: the actual domain knowledge
• Evidence: contributor's stated experience or data source
• Contributor: username for attribution

If any of these are missing or unclear, don't guess. Ask the user:

Issue #NNN by @contributor is about [topic] for /[skill]. But I'm not sure about: [what's unclear]

A) I think it goes in references/[file] — proceed B) Ask the contributor for clarification (I'll comment on the Issue) C) Skip this one

STOP. Wait for answer.

Step 2: Read the target skill's current content

TARGET_SKILL="<from Issue>"
ls "skills/$TARGET_SKILL/references/" 2>/dev/null

Read the target file (e.g., references/gotchas.md) to understand:

• Current structure and numbering
• Existing content on the same topic
• Style and format used

If the target skill has no references/ directory yet (it's one of the 8 unsplit skills):

/[skill] doesn't have a references/ directory yet.

A) Create references/ first — I'll run /skill-review refactor [skill] before integrating B) Add to SKILL.md.tmpl directly — append to the existing content (less ideal but works) C) Skip — wait until the skill is refactored

STOP. Wait for answer. Recommend A if the skill is >300 lines.

Step 3: Contradiction check

# Extract key terms from the contribution
# Search all skills for the same topic
grep -rn "KEYWORD1\|KEYWORD2\|KEYWORD3" skills/*/references/*.md skills/*/SKILL.md.tmpl 2>/dev/null | grep -v "SKILL.md:" | head -20

Compare the contribution's claims against existing content:

Check	Result
Same metric exists in target file?	If yes: this is an UPDATE, not an ADD
Same metric exists in OTHER skills?	If yes: check for contradiction
Contradiction found?	If yes: ⚠️ flag, do not resolve

If contradiction found, document it:

⚠️ CONTRADICTION DETECTED

Existing (skills/balance-review/references/scoring.md L27):
  "D1 retention > 40% = good"

Contributor (Issue #NNN) says:
  "D1 retention 35-45% = average for F2P casual mobile, > 50% = good"

These may both be correct for different contexts (premium vs F2P).
Maintainer decision needed.

Step 4: Convert to proper format

Apply the conversion template from references/format-templates.md:

• Gotcha → numbered item with bold summary + wrong → correct → reasoning → source
• Benchmark → table row update with (updated YYYY-MM, source: XXX)
• Forcing question → QN format with push-back + red flags + STOP
• Scoring → ⚠️ flag as scope change (scoring changes modify SKILL.md.tmpl)

Write the converted content to the target file using Edit tool.

Step 5: Validation checklist

Run through ALL checks in references/validation-checklist.md:

bun run build
bun test

Present the checklist result:

Validation:
  Content in right place:  ✅
  No contradictions:       ✅ (or ⚠️ flagged)
  Format matches:          ✅
  Build + test pass:       ✅
  Within scope:            ✅ (or ⚠️ scope change)
  PR description:          ✅

If any ❌: fix it before proceeding. If ⚠️: include in PR description.

Step 6: Create branch and commit

ISSUE_NUM="<number>"
SKILL_NAME="<target skill>"
BRANCH="contribute/${ISSUE_NUM}-${SKILL_NAME}"
git checkout -b "$BRANCH"
git add "skills/$SKILL_NAME/"
git commit -m "improve($SKILL_NAME): integrate Issue #$ISSUE_NUM

<1-line summary of what was added/changed>

Source: Issue #$ISSUE_NUM by @<contributor>
Type: <gotcha|benchmark|forcing-question|scoring>
Evidence: <contributor's stated experience>

Co-Authored-By: Claude Opus 4.6 (1M context) <[e-mail]>"

Step 7: Create PR

gh pr create --title "improve($SKILL_NAME): <summary>" --body "$(cat <<'EOF'
## Summary

Integrates domain knowledge from #ISSUE_NUM into `/SKILL_NAME`.

**Type:** gotcha / benchmark / forcing question / scoring calibration
**Contributor:** @USERNAME
**Evidence:** CONTRIBUTOR_EVIDENCE

## Changes

- **File:** `skills/SKILL_NAME/references/FILE.md`
- **What:** DESCRIPTION_OF_CHANGE

## Validation

| Check | Result |
|-------|--------|
| Content in right place | ✅ |
| No contradictions | ✅ / ⚠️ |
| Format matches | ✅ |
| Build + test pass | ✅ |
| Within scope | ✅ / ⚠️ |

CONTRADICTION_FLAGS_IF_ANY

## Review needed

- [ ] Domain correctness — is this contribution factually right?
- [ ] Context applicability — does this apply broadly or only to specific game types?

Closes #ISSUE_NUM

---
Integrated by `/contribute-review`
EOF
)"

Replace all placeholders with actual values.

Step 8: Return to main

git checkout main

Present summary:

✅ Issue #NNN → PR #PPP

Skill: /[name]
File: references/[file]
Type: [gotcha/benchmark/forcing-question/scoring]
Contributor: @username

Flags:
  [list any ⚠️ items that need maintainer attention]

PR is ready for your review.

---

Operation: Scan Open Issues

Step 1: List domain-knowledge Issues

gh issue list --state open --label "domain-knowledge,gotcha,benchmark,forcing-question,scoring" --json number,title,labels,author,createdAt --limit 50

If no label filter works (labels might not exist yet):

gh issue list --state open --json number,title,labels,body,author,createdAt --limit 50

Classify each Issue:

• Domain contribution — matches one of the 4 Issue templates (gotcha, benchmark, forcing question, scoring)
• Bug report — not a contribution, skip
• Feature request — not a contribution, skip
• Unclear — can't tell, flag for manual triage

Step 2: Present queue

Domain Knowledge Issues
═══════════════════════════════════════════════════
| # | Title | Type | Skill | Age | Priority |
|---|-------|------|-------|-----|----------|
| 42 | gotcha: idle inflation | gotcha | /balance-review | 3d | 🔴 critical skill |
| 38 | fix D1 retention | benchmark | /game-review | 5d | 🟡 important |
| 35 | add forcing Q | question | /pitch-review | 7d | 🟡 important |
═══════════════════════════════════════════════════

Priority based on:
  🔴 = targets a critical-need skill (from CONTRIBUTING.md)
  🟡 = targets an important-need skill
  ⚪ = targets a stable skill

Process which one?
A) #42 (highest priority)
B) #38
C) #35
D) Process all in priority order

STOP. Wait for user to pick.

If user picks D: process each sequentially. Create a separate branch and PR for each Issue (never batch multiple Issues into one PR).

---

Edge Cases

Situation	Action
Issue is too vague to convert	Comment on Issue asking for specifics. Don't create PR.
Contributor targets a skill that doesn't exist	Ask user: create the skill, or redirect to closest existing skill?
Same contribution already exists	Close Issue as duplicate, link to the existing content with file + line reference.
Contribution is wrong (you can tell from basic logic)	You cannot decide this. Flag in PR: "This may contradict [basic principle]. Maintainer should verify."
Contribution requires SKILL.md.tmpl changes	Flag as ⚠️ scope change. Create PR with the changes but mark as draft.
Target skill has no references/ yet	Recommend /skill-review refactor first, or add to SKILL.md.tmpl with a TODO marker.
Multiple Issues for the same skill	Process each as a separate PR. Don't batch.
Issue is in English but skill content is mixed	Match the language of the existing content in the target file.

Anti-Sycophancy

Never say:

• "Great contribution!" (you don't know if it's correct)
• "This will really improve the skill" (you don't know until a domain expert reviews)
• "The contributor clearly knows their stuff" (not your judgment to make)

Always say:

• "Issue #NNN proposes [specific change]. I've formatted it and checked for contradictions."
• "There's a potential conflict with [existing content]. Maintainer needs to decide."
• "Validation passed / failed on [specific checks]."

Important Rules

• One Issue = one PR. Never batch multiple contributions.
• Never resolve domain conflicts. Flag both sides, let maintainer decide.
• Always attribute. Every added line traces back to the contributor and their stated evidence.
• Build must pass. Don't create PR if bun test fails.
• Return to main. Always git checkout main after creating the PR.
• Comment on the Issue. After creating the PR, comment on the original Issue:

  gh issue comment "$ISSUE_NUM" --body "PR #PPP created to integrate this contribution. Thanks @contributor!"
  

Review Log

[ -n "$_GG_BIN" ] && "$_GG_BIN/gstack-review-log" '{"skill":"contribute-review","timestamp":"TIMESTAMP","status":"STATUS","issue":"ISSUE_NUM","target_skill":"TARGET","type":"TYPE","contradictions":N,"scope_changes":N,"commit":"COMMIT"}' 2>/dev/null || true