Contribution Map

Goal

Find credible, mergeable contribution lanes for Ren that improve the Garry system without duplicating crowded PR areas.

Scoring Lens

Opportunity Score = Impact x Merge Probability / Effort.

Impact:

• Does it improve setup, reliability, correctness, docs, or eval credibility?
• Does it affect a high-frequency workflow?
• Is there maintainer signal?

Merge probability:

• Is the issue recent and clear?
• Is the surface small?
• Are duplicate PRs absent?
• Does the change match repo style?

Effort:

• How many files?
• Can we test locally?
• Does it need credentials, Windows, Supabase, OAuth, or external services?

Lane 1: gbrain Doctor/Audit Accuracy

Theme: reduce noisy or misleading health checks.

Why it matters: gbrain's value depends on trust. If doctor/maintain/check commands produce false positives, users stop trusting memory operations.

Likely targets from current issue/PR themes:

• source state audit false positives
• doctor checks around effective dates, archived/deleted state, citations, and frontmatter
• clearer diagnostic messages and remediation hints

Score: high.

• Impact: 4
• Merge probability: 4
• Effort: 2
• Score: 8

First move: pick one narrow diagnostic issue, reproduce locally, add a failing test around the exact false positive, then patch the check.

Lane 2: gstack <-> gbrain Sync Diagnostics

Theme: make /sync-gbrain and /setup-gbrain failures explain themselves.

Why it matters: this is the bridge between process and memory. If it fails, the whole "compounding agent" story weakens.

Potential improvements:

• clearer capability check output
• dry-run mode that lists source, strategy, MCP status, and guidance changes
• better stale-guidance removal
• explicit trust-tier reminders

Score: good but duplicate-prone.

• Impact: 5
• Merge probability: 3
• Effort: 3
• Score: 5

First move: run duplicate search across open/closed PRs before touching code. This lane is strategically important but likely crowded.

Lane 3: MCP Schema and Tool Contract Hardening

Theme: stricter input validation, safer errors, and clearer operation contracts.

Why it matters: HTTP MCP with OAuth and source scoping is a trust boundary. Bad contracts create silent corruption or leaked access.

Score: selective.

• Impact: 5
• Merge probability: 2
• Effort: 4
• Score: 2.5

Reason for caution: MCP contract areas tend to be crowded and architectural. Only pursue if we find a specific unhandled edge with failing test evidence.

Lane 4: gbrain-evals Reproducibility Polish

Theme: make benchmark setup and reports easier to verify.

Why it matters: gbrain-evals is the public proof layer. Reproducibility docs and harness polish increase credibility without risky product changes.

Possible contributions:

• preflight script that checks dataset path, API keys, cache, and adapter availability
• "run one tiny smoke benchmark" docs
• report template consistency
• clearer cost/time expectations

Score: strong story value.

• Impact: 4
• Merge probability: 4
• Effort: 2
• Score: 8

First move: run existing quickstart, capture actual failure friction, patch docs or preflight with testable evidence.

Lane 5: Windows/Install Reliability

Theme: fix cross-platform setup pain.

Why it matters: setup is high-leverage, especially for gstack's "30 seconds" promise.

Score: caution.

• Impact: 4
• Merge probability: 3
• Effort: 4
• Score: 3

Reason for caution: we need a Windows runner or verified repro. Without it, risk of fabricated fixes is too high.

Recommended First Contribution

Start with gbrain-evals reproducibility or gbrain doctor/audit accuracy.

Why:

• Narrow enough to verify.
• Storyable: "the proof layer should be reproducible" or "memory health checks must be trustworthy."
• Lower duplicate risk than sync/MCP work.
• Strong fit with Ren's standards: failing test first, source verification, no speculative API use.

Duplicate Check Protocol

Before implementation:

1. Search open and closed PRs by issue keywords.
2. Search issue comments for claimed fixes.
3. Check recent PRs from the last 30 days.
4. Check whether maintainer has already pointed at a preferred direction.
5. If a duplicate exists, comment with evidence or pick another issue.

Contribution Output Standard

For any PR:

• one concern only
• failing test first
• API/source verification for every API used
• local test evidence
• PR description calibrated to repo style
• explicit note on what the fix does not attempt

Live Repo Signal, Deep Pass

Current themes:

• gstack: Windows Bun build failures, gbrain sync hardening, browser/CORS, design image timeouts, Codex review behavior.
• gbrain: doctor/audit noise, embedding provider config, migration wedges, MCP/admin schema/transport, autopilot/source sync, transcript chunking.
• gbrain-evals: BrainBench API drift, missing multimodal fixture fetch path, adapter shootout draft.

Ranked Contribution Lanes, Updated

1. Verify Existing gbrain-evals PRs Instead Of Duplicating Them

Score: Impact 3 x Merge Probability 5 / Effort 1 = 15.

Evidence:

• Issue #2 has open PR #7: fix(cat2,cat10): update extractPageLinks call sites to new 5-param API.
• Issue #3 has open PR #4: feat(eval): cat11 multi-modal fetcher + fixtures + scorecard.
• PR #8 is Garry's draft embedder shootout.

Best contribution is not a new PR. It is a verification comment with exact local evidence.

Exact first step:

cd /Users/bobshah/.openclaw/ren-workspace/gbrain-evals
gh pr checkout 7
bun install
bun run eval:brainbench:smoke

Then repeat for PR #4:

gh pr checkout 4
bun run eval:cat11

Avoid:

• Do not submit another extractPageLinks fix.
• Do not add a new multimodal fetcher until PR #4 is evaluated.
• Do not touch benchmark scoring unless the PR fails reproducibly.

2. Fix gbrain Transcript Fenced-Code Chunk Noise

Target: garrytan/gbrain#1097.

Score: Impact 5 x Merge Probability 3 / Effort 2 = 7.5.

Evidence:

• Issue reports 1,692 [Bash] fence.sh chunks, 1,089 under 200 chars, crowding out real transcript content.
• Local source confirms fenced-code extraction lives in gbrain/src/core/import-file.ts, via extractFencedChunks(), FENCE_TAG_TO_PSEUDO_PATH, and chunk_source='fenced_code'.
• Duplicate search found no direct PR for transcript fence suppression. Related but not duplicate: old merged chunking PR #422 and unrelated Astro PR #850.

Implementation shape: add a failing test around transcript markdown with several one-line bash fences, then suppress tiny fenced-code chunks while preserving the parent markdown chunk.

Exact first step:

cd /Users/bobshah/.openclaw/ren-workspace/gbrain
gh pr list --repo garrytan/gbrain --state all --search "fenced code transcript chunks"
rg -n "extractFencedChunks|chunk_source: 'fenced_code'|FENCE_TAG_TO_PSEUDO_PATH" src test

Avoid:

• Do not delete all fenced-code extraction; docs/architecture examples need it.
• Do not make this global without tests proving substantial code fences still chunk.
• Do not use SQL cleanup as the fix; issue says chunks regenerate on sync.

3. Make frontmatter audit Respect .gbrain-ignore

Target: garrytan/gbrain#1066.

Score: Impact 4 x Merge Probability 3 / Effort 2 = 6.

Evidence:

• Issue says gbrain frontmatter audit reports ignored paths as MISSING_OPEN.
• Local source shows gbrain/src/commands/frontmatter.ts delegates audit to scanBrainSources from src/core/brain-writer.ts.
• Related open PR #922 skips generated dirs in frontmatter walkers, but duplicate search did not show a direct .gbrain-ignore audit fix.

Exact first step:

cd /Users/bobshah/.openclaw/ren-workspace/gbrain
gh pr list --repo garrytan/gbrain --state all --search "gbrain-ignore frontmatter audit"
rg -n "scanBrainSources|gbrain-ignore|collectFiles|frontmatter audit" src test

Avoid:

• Do not bundle this with convention-file allowlists from #1074.
• Do not change sync semantics; only align audit with existing ignore semantics.
• Do not add broad glob behavior without reading the existing ignore parser/source walker code.

4. Reduce Doctor Freshness Noise In Test/Fixture Contexts

Target: garrytan/gbrain#1081.

Score: Impact 3 x Merge Probability 3 / Effort 2 = 4.5.

Evidence:

• Issue asks for fewer spurious doctor/sync freshness warnings in fixture/test contexts.
• Related open PR #936: Refresh source sync timestamp when unchanged.
• Closed PRs #961 and #1026 touched sync freshness and last_sync_at.

Avoid for now unless PR #936 leaves a narrow uncovered edge.

5. Avoid gstack Sync/Windows Lanes For Now

Score: Impact 5 x Merge Probability 1 / Effort 3 = 1.7.

Evidence:

• gstack has open sync PRs #1547, #1513, #1461, #1433, #1468, #1418.
• Windows build has open PRs #1531, #1544, #1460, #1480.
• Recent issue #1545 already links PR #1546.

Avoid:

• Do not open a new gbrain sync hardening PR.
• Do not submit Windows fixes without a Windows repro runner.
• Do not work from old issue titles; many are already folded into Garry-owned fix waves.

Recommendation

Best next move: start with gbrain-evals PR verification because it has the highest merge usefulness per minute and zero duplicate-code risk.

Best code PR candidate: gbrain#1097 transcript fenced-code chunk suppression. It is specific, source-backed, testable, and not obviously duplicated.