resourceful

A Claude Code skill that forces Claude to exhaust every available resource before saying "I can't / I don't know / not sure". Climbs a five-tier ladder, blocks lazy capitulation with a Stop hook.

The pain it solves

You ask Claude something. Claude hedges — "I'm not sure", "it depends", "I'd need more context" — without having opened a single file, run a single search, or spawned a single sub-agent. You correct it. Claude apologises, tries one thing, hedges again. Three rounds later you realise Claude could have answered the question on turn one by reading one file plus running one web search.

This is not Claude being lazy. It's a default that optimises for "don't claim things you didn't verify" and accidentally produces "give up before claiming anything". The fix is not more confidence — it's more climbing.

resourceful flips the default: capitulation requires proof of effort. Specifically:

1. A five-tier resource ladder. Local filesystem → system/git history → authenticated MCPs (Gmail, Calendar, Drive, GitHub, etc.) → open web + Context7 docs → delegated sub-agents.
2. A banned-phrase list. "I'm not sure", "não sei", "outside my reach", "would need more info", "hard to say", and 20+ siblings.
3. A Stop hook. Scans every outgoing assistant message. If it contains a banned phrase AND fewer than two ladder tiers were climbed AND no escalation report is present → blocks the message and forces another investigation pass.
4. The escalation report. The only legitimate "blocked" — a structured template that names exactly what was tried per tier and exactly what input would unblock. No vague "I'd need more context".

The point isn't to make Claude omniscient. Some questions genuinely aren't answerable from where it sits. The point is that "I can't" must be proven, not assumed.

Quick demo

You: Where do we set the default rate limit?

Claude (without resourceful):
  "I'm not sure where it's set — it could be in middleware or environment variables.
  Could you share where you'd expect to find it?"

──────────────────────────────────────────────────────

You: Where do we set the default rate limit?

Claude (with resourceful):
  [Grep -r 'rateLimit' src/                      → 14 hits]
  [Read src/middleware/rate-limit.ts:1-80]
  [git log --all -S'RATE_LIMIT_DEFAULT'           → commit a1b2c3d]
  [Read .env.example                              → RATE_LIMIT_DEFAULT=60]

  Default lives in RATE_LIMIT_DEFAULT (currently 60 in .env.example),
  consumed by src/middleware/rate-limit.ts:42. Introduced in commit a1b2c3d.

Same question. With the skill installed, Claude climbed L1 + L2 of the ladder before answering. The user got a precise answer on turn one.

Install

Inspect-then-run:

git clone https://github.com/pedroreisper/resourceful
cd resourceful
less install.sh           # short, no obfuscation
bash install.sh --hook    # installs skill + wires the Stop hook

Or one-liner (trust the URL):

curl -fsSL https://raw.githubusercontent.com/pedroreisper/resourceful/main/install.sh | bash -s -- --hook

Then /reload your Claude Code session.

Manual install

mkdir -p ~/.claude/skills
git clone https://github.com/pedroreisper/resourceful ~/.claude/skills/resourceful
bash ~/.claude/skills/resourceful/hooks/install_hook.sh

Uninstall

bash install.sh --uninstall   # removes the skill
# remove the Stop hook entry in ~/.claude/settings.json (search for pre_capitulation.py)

How it works

The five tiers

Tier	What	Example tools
L1 Local	Working tree, ~/.claude/, dotfiles, CLAUDE.md chain	Read, Grep, Glob
L2 System	Git history, GitHub, Spotlight, processes, env	git log, gh search, mdfind, launchctl list
L3 MCPs	Gmail, Calendar, Drive, GitHub org, GoCardless, memory graph, Playwright, computer-use	mcp__claude_ai_Gmail__search_threads, etc.
L4 Web	Live web + current library docs	WebSearch, WebFetch, mcp__context7__*
L5 Agents	Delegated specialists	Agent(researcher), Agent(code-explorer), parallel general-purpose

Two-tier minimum before any hedge. Five tiers preferred when the user explicitly asks for max effort ("be resourceful", "don't give up").

The hook

hooks/pre_capitulation.py runs on Stop events. It:

1. Reads the latest assistant message text from the session transcript.
2. Runs the banned-phrase regex catalogue against it (references/banned-phrases.md).
3. Walks the recent transcript and counts distinct ladder tiers exercised (via tool-call classification).
4. Looks for a valid escalation report (BLOCKED: header + Tried: table with ≥2 non-skipped tiers + Needed: line).
5. Blocks the Stop only if: banned phrase present AND <2 tiers climbed AND no valid escalation. Otherwise allows.

The escalation report

The only legitimate "blocked" looks like this:

BLOCKED: Cannot decide between two equally valid migration paths without a product call.

Tried:
  L1 (local):   read src/auth/{legacy.ts,session.ts}, CLAUDE.md auth section
  L2 (system):  git log --all -S'sessionToken' (12 commits; no consensus)
  L3 (mcps):    Gmail search 'session migration' (3 threads, inconclusive); GH PR #318 closed, #421 stalled
  L4 (web):     WebSearch 'NextAuth v6 session migration breaking change' (docs incomplete)
  L5 (agents):  researcher spawned — confirms ambiguity in upstream docs

Needed: Pedro to choose (a) drop legacy `sessionToken` at migration vs. (b) dual-write for one cycle.

Hedging without this shape is auto-blocked.

When to use

Situation	How the skill fires
User invokes /resourceful	Manual — top of session or mid-task.
User says "be resourceful", "don't give up", "go deeper", "investiga mais"	Trigger phrase — bar rises to all 5 tiers.
Claude is about to type "I'm not sure"	Stop hook — blocks unless tiers were climbed.
Research-shaped questions ("how do I…", "where is…", "is X possible…")	Skill self-applies as a checklist.

When NOT to use

• Trivial single-tool tasks.
• Pure-opinion asks ("which name do you prefer").
• The user has explicitly accepted a hedge ("just guess").
• Already produced a clean escalation report → answer the user's follow-up, don't re-climb.

Interaction with other Claude Code skills

• did-it-actually verifies output against the request. resourceful governs input — what was investigated. They compose: run resourceful for input quality, did-it-actually for output quality.
• karpathy-guidelines says "surface your assumptions". resourceful says "if your assumption is checkable, check it".
• briefing (Pedro's morning briefing) is a packaged L3 climb. paper-lookup is an L4 specialisation for academic queries.

File layout

resourceful/
├── SKILL.md                                # main skill spec, loaded by Claude Code
├── README.md                               # this file
├── LICENSE                                 # MIT
├── install.sh                              # installer
├── references/
│   ├── resource-ladder.md                  # the five tiers, full tool examples
│   ├── banned-phrases.md                   # regex catalogue + accepted replacements
│   ├── escalation-template.md              # the BLOCKED report format
│   └── examples.md                         # three worked runs
├── hooks/
│   ├── pre_capitulation.py                 # Stop hook
│   └── install_hook.sh                     # wires the hook into settings.json
└── scripts/
    └── doctor.sh                           # verify install + hook wiring

Limitations

• The hook is a regex pass — it will miss creatively-phrased hedges and occasionally false-positive on a literal phrase inside quoted user text. Tune references/banned-phrases.md to your taste.
• Tier classification of Bash calls is heuristic (looks at the command string for git/gh/mdfind etc.). A bash one-liner that mixes Tier 1 and Tier 2 work is counted as one tier.
• The hook reads the session transcript file directly. Format changes in future Claude Code versions may require a small update to read_transcript().
• The skill assumes English + Portuguese hedge vocabulary. Add patterns to references/banned-phrases.md for other languages.

Contributing

PRs welcome. Useful additions:

• More banned-phrase patterns in other languages.
• More tier classifiers (especially for new MCP servers).
• More worked examples in references/examples.md — particularly the legitimate-escalation kind.

License

MIT. See LICENSE.