| name | addvalue |
| description | Deep-reviews a GitHub repo, local project, CLI, docs, or product for high-leverage bugs, features, UX gaps, and inspiring upgrades—not typo farms. Use when the user says /addvalue, add value, find improvements, or what to build next. Do not use for a /better polish pass, a reproduce-then-fix hunt (bug-hunter), or mass good-first-issue PRs. |
/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)
| Partner | When | How |
|---|
| This agent (default) | Always | Full review + implement |
| Ollama Cloud GLM | User says /addvalue --ollama or /ollama mid-pass | Load ollama skill; one high-reasoning plan call; execute or merge with your plan |
| Local Ollama | User says /addvalue --local or /local | Load local skill; use as second opinion only |
| agy / agent CLIs | User names a CLI (agy, hermes, project scripts) | Prefer project engines over inventing parallel tools; pass paths not huge file dumps |
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
- Scope lock — name the target and one primary outcome before editing.
- Read before invent — README, CONTRIBUTING, AI_POLICY, recent issues/PRs, architecture entrypoints. No drive-by.
- Value > vanity — reject star-farm, typo-only, comment-churn, duplicate open PRs.
- 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.
- Human gate for upstream — for third-party GitHub PRs, stop at draft +
Take OWNER/REPO#N unless already approved.
- Reproduce / accept — bugs need a failing test or exact repro; features need acceptance checks from issues/docs/users.
- Verify with evidence — project’s own test/lint/build; report commands + exit codes.
- 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:
| Field | Example |
|---|
| Target | pypa/hatch, ~/projects/foo, . |
| Kind | library / app / CLI / docs / monorepo / playbook |
| Intent | contribute upstream / improve own product / invent roadmap |
| Constraint | max 1 PR, no UI, Windows-only, etc. |
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:
| Axis | High score means |
|---|
| User impact | Pain or desire is real and frequent |
| Leverage | One change unlocks many workflows |
| Fit | Matches project style and maintainer taste |
| Feasibility | Clear repro/acceptance; you can verify |
| Novelty | Not already PR’d / not trivial |
| Hardness | Would take a sharp maintainer >1 day, or needs deep domain/design |
| Inspiration | Users will say “finally” — new capability, not polish |
| Risk | (invert) low chance of breaking core contracts |
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:
- Repro or acceptance checks
- Files likely touched
- Smallest design that matches existing patterns
- Verify commands
- 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:
| Lens | Questions |
|---|
| Correctness | Silent data loss? Wrong defaults? Race? |
| Features | What’s half-built? What’s documented but missing? |
| UX / DX | Confusing errors? Missing --help examples? Slow feedback? |
| Perf | Hot paths? Accidental O(n²)? |
| Security / safety | Trust boundaries? Path traversal? Secret leakage? |
| Platform | Windows path/newline/env gaps? |
| Docs | Lies, missing recipes, no migration notes |
| Inspiration | What would make a power user say “finally”? |
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
| Need | Use |
|---|
| Contract before multi-session work | /goal |
| Autonomous until criteria | /goal-loop |
| Quality polish after implement | /better |
| Many unique variants | /scale |
| Cloud planner partner | /ollama inside or after /addvalue |
| Recurring re-scan | /loop 1d /addvalue . |
Progressive disclosure
Installation paths
- Skill: this folder's
SKILL.md
- Command: optional
/addvalue command file in the host agent
