Addvalue

/addvalue — Find and ship real value

Purpose

Review a target carefully (remote Git repo, local folder, library, CLI, UI, docs site, or product surface) and produce a ranked plan of improvements that actually help users or maintainers. Then optionally implement the top item.

This is not “open 20 tiny PRs.” Prefer one hard, reviewable change over many shallow ones.

Triggers

• /addvalue [path|owner/repo|.]
• “add value”, “how can this be improved”, “inspiring updates”, “what should we build”
• Track B contribution hunting when quality > volume

Partners (optional)

Paid/cloud partners: honor the user’s Paid Models — Ask First rule. /ollama is standing approval for one GLM planner call on that turn. Ask before other paid APIs.

Hard rules

1. Scope lock — name the target and one primary outcome before editing.
2. Read before invent — README, CONTRIBUTING, AI_POLICY, recent issues/PRs, architecture entrypoints. No drive-by.
3. Value > vanity — reject star-farm, typo-only, comment-churn, duplicate open PRs.
4. Hard + inspirational bar (non-negotiable) — Prefer work a sharp maintainer would not clear in an afternoon. Reject “correct but small” DX/docs/pattern-rebase fixes unless the user explicitly lowers the bar. Winning work should be either:
   • Hard: races, protocol/semantics bugs, cross-layer design, subtle correctness with non-obvious tests, or
   • Inspirational: a capability users invent workarounds for; something that changes what the tool can do, not just how you debug it.
5. Human gate for upstream — for third-party GitHub PRs, stop at draft + Take OWNER/REPO#N unless already approved.
6. Reproduce / accept — bugs need a failing test or exact repro; features need acceptance checks from issues/docs/users.
7. Verify with evidence — project’s own test/lint/build; report commands + exit codes.
8. No fake done — ledger or session note: what changed, how verified, what remains.

Explicit rejects (fail the bar)

• Explain/debug CLIs for existing behavior
• Single-file pattern/rebase fixes with clear recipes
• Good-first-issue labeled work unless it hides a deep bug
• Anything a competent maintainer would ship between meetings
• Competing open PRs / already-assigned maintainer work you cannot uniquely advance

Workflow

Copy and track:

ADDVALUE Progress:
- [ ] 1. Target + intent
- [ ] 2. Map the system
- [ ] 3. Signal scan (issues, users, friction)
- [ ] 4. Opportunity bank + score
- [ ] 5. Pick ONE winner
- [ ] 6. Plan (smallest correct change)
- [ ] 7. Implement + verify (if in scope)
- [ ] 8. Report

1. Target + intent

Identify:

If target missing, default to current workspace root.

2. Map the system

Spend tokens on structure, not trivia:

• Entry points (CLI, main, routes, pyproject scripts)
• Core domain modules (where value lives)
• Test/verify path (hatch test, pytest, npm test, …)
• Contribution/AI policy if present
• Recent release notes / changelog tone

For remote repos: gh repo view, gh issue list, gh pr list, clone only when implementing.

For local / non-git projects: same mapping via filesystem + run scripts; VCS optional.

3. Signal scan

Gather friction from:

• Open issues (bugs and enhancements; “help wanted”; milestone)
• Closed-but-painful issues / “won’t fix” that aging may reopen
• Docs vs reality (README steps that fail)
• Error paths, Windows/macOS gaps, silent failures
• Competitor / sibling tools (what users already expect)
• Your own dry-run of the happy path

Optional partner pass: ask Ollama Cloud (/ollama) for a ranked opportunity list given only paths + issue titles (not full dumps).

4. Opportunity bank + score

Write 5–12 candidates. Score each 1–5 on:

Winner score = impact + leverage + fit + feasibility + novelty + hardness + inspiration − risk.

Floor: reject candidates with hardness < 4 and inspiration < 4 unless the user asked for a small win.

Discard: duplicates of open PRs, policy violations, scope bombs, “rewrite the world.”

5. Pick ONE winner

State in one paragraph:

• Problem / missing capability
• Who benefits
• Why this beats the runners-up
• Out of scope for this pass

6. Plan

Minimum plan:

1. Repro or acceptance checks
2. Files likely touched
3. Smallest design that matches existing patterns
4. Verify commands
5. Upstream gate (if any)

Use Plan mode when trade-offs are large; otherwise implement.

7. Implement

• Smallest diff; match project style
• Tests first when fixing bugs
• No Co-authored-by LLM on third-party PRs
• Disclose AI if the project’s CONTRIBUTING requires it
• Stop before gh pr create unless user said Take OWNER/REPO#N

8. Report

## ADDVALUE: <target>

**Winner:** <title> (<issue/url or local>)
**Why:** <one line>

### Also considered
- ...

### Done / next
- Implemented: ...
- Verified: `<cmd>` → exit N
- Blocked / gate: ...

Domains the review must consider

Do not only hunt bugs. Explicitly scan:

Anti-patterns

• Mass AI PRs / typo farms / readme churn for graph greens
• Picking an issue that already has an active PR
• “Improvements” that fight the maintainer’s stated design
• Partner model dumps that you paste as the PR body unread
• Claiming value without verify evidence
• Opening a third upstream PR while two are already waiting (unless user overrides)

Compose with other modes

Progressive disclosure

• Scoring templates + output schemas → reference.md
• Worked examples → examples.md

Installation paths

• Skill: this folder's SKILL.md
• Command: optional /addvalue command file in the host agent