contribute-review

Category: Docs & Knowledge | Uploader: fagemx | Downloads: 0 | Version: v1.0（Latest）
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.
Changelog: Source: GitHub https://github.com/fagemx/gstack-game
Directory Structure

Current level: tree/main/.claude/skills/contribute-review/
📁 references/
- 📄 format-templates.md 4.5 KB
- 📄 integration-rules.md 2.8 KB
- 📄 validation-checklist.md 2.6 KB
📄 SKILL.md 14.5 KB
SKILL.md

---
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
---
<!-- Internal maintenance skill — edit this file directly -->

## Preamble (run first)

```bash
_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)

```bash
_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)

```bash
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

```bash
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

```bash
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

```bash
# 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`:

```bash
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

```bash
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) <noreply@anthropic.com>"
```

### Step 7: Create PR

```bash
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

```bash
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

```bash
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):

```bash
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:
  ```bash
  gh issue comment "$ISSUE_NUM" --body "PR #PPP created to integrate this contribution. Thanks @contributor!"
  ```

## Review Log

```bash
[ -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
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
contribute-review

Directory Structure

SKILL.md

Report

Notice
