Skip to content

🧠 refactor(claude.md): verify-context doctrine + tighter trigger + MCP merge#130

Merged
ZaxShen merged 1 commit into
devfrom
refactor/claude-md-verify-context-doctrine
Apr 26, 2026
Merged

🧠 refactor(claude.md): verify-context doctrine + tighter trigger + MCP merge#130
ZaxShen merged 1 commit into
devfrom
refactor/claude-md-verify-context-doctrine

Conversation

@ZaxShen
Copy link
Copy Markdown
Contributor

@ZaxShen ZaxShen commented Apr 26, 2026

Summary

Three changes per user line-by-line audit on PR #129:

  1. Trigger rule compressed (14 lines β†’ 8)
  2. MCP + agent model merged (12 lines β†’ 4) β€” full agent model already in docs/AGENTS.md
  3. NEW: 'Before answering β€” verify context' section (10 lines) β€” two concrete checks bro runs before any substantive answer

The verify-context doctrine

User wanted explicit anti-guessing rules with two concrete questions:

  • 'Is this the industry standard or the best way?'
  • 'Do you have enough context from DB, codebase, user's ideas?'

Web-researched (see machinelearningmastery.com hallucination tricks, promptfoo prevent-llm-hallucinations) and polished into:

## Before answering β€” verify context

**Don't guess. Don't fabricate. Don't be a yes-man.** Before you plan, decide, or answer a substantive question, run two checks:

1. **Context check** β€” *do I have enough?* Pull from this priority order: codebase (Read / Glob / Grep / git), DB (MCP queries), web (WebFetch / WebSearch for upstream docs / specs / standards), then training-data fallback. If context is thin, **say so** and either ask the Human or run the lookup. Thin context β†’ 'I'm not sure, checking…' beats inventing an answer.
2. **Standards check** β€” *is what I'm about to recommend the industry standard or the best way?* If you're not sure, do the lookup. If a domain expert (legal, security, perf, etc.) would handle it better than bro, propose `tmb_agent-creator` to spawn the specialist. Bro should be professional and competent across general SWE work; for genuinely specialized domains, escalate.

When you're guessing, label it. Cite the source when relevant.

Replaces the implicit 'don't be a yes-man' that lived only in tmb_concerns-protocol (which only fires on disagreement). This new section fires on every substantive answer.

Subagent CLAUDE.md isolation (defense in depth)

Per user concern about permission leakage, added one line to agents/swe.md and agents/pr-reviewer.md:

Do not read project-level CLAUDE.md β€” that file is bro's persona; this agent's prompt is canonical for [SWE / review] work.

CC does NOT auto-load CLAUDE.md into subagent context (subagents get their own system prompt from agents/<name>.md). This line is belt-and-suspenders against a subagent inadvertently Reading the file from disk and following bro-only rules.

Followups (filed separately)

  • Q1: A/B prompt testing in L5/L6 β€” to be filed as new GH issue
  • Q6: per-project AGENTS.md auto-update + name-collision strategy with user's local agents

Local verification

  • agent-line-budget passes (swe 23, pr-reviewer 28; cap 30)
  • CLAUDE.md: 112 β†’ 103 lines (cumulative origin β†’ here: 268 β†’ 103, 62% reduction)

…P merge

User feedback: trim trigger block, merge MCP/agent-model into one section,
and add an explicit anti-guessing doctrine. The vague 'no yes-man' framing
was rejected; replaced with two concrete checks (informed by web research
on anti-hallucination prompting techniques in 2026).

## CLAUDE.md changes (112 β†’ 103 lines)

### Trigger rule compressed (14 lines β†’ 8)

Was: 4 sub-sections (sticky check / not-yet-activated / deactivation /
when-in-doubt) with full explanations.
Now: 4 bullet points covering all four cases inline.

### MCP + agent model merged (12 lines β†’ 4)

The MCP caller-id rule + agent-layer-model summary collapse into one
'## MCP' section with a pointer to docs/AGENTS.md. Forbidden tools detail
already lives in tmb_mcp-error-handling skill.

### NEW: 'Before answering β€” verify context' section (10 lines)

Two checks bro must run before any substantive answer:

1. **Context check** β€” pull from priority order: codebase β†’ DB β†’ web β†’
   training-data fallback. If context is thin, say so + ask/lookup.
2. **Standards check** β€” is this the industry standard / best way? If
   unsure, lookup. If a domain expert would handle it better, propose
   tmb_agent-creator.

Replaces the implicit 'don't be a yes-man' that existed only in
tmb_concerns-protocol (which only fires on disagreement). This new
section fires on every substantive answer.

Web-research-informed: ICE method (Instructions/Constraints/Escalation),
source-grounded prompting, self-verification β€” see
machinelearningmastery.com & promptfoo docs on hallucination mitigation.

## Subagent prompt hardening

Added one defensive line to agents/swe.md and agents/pr-reviewer.md:

  **Do not read project-level CLAUDE.md** β€” that file is bro's persona;
  this agent's prompt is canonical for [SWE / review] work.

Mitigates the theoretical risk of subagents inadvertently following
bro-only rules if they happen to Read CLAUDE.md from disk. (CC does
NOT auto-load CLAUDE.md into subagent context, so this is defense in
depth, not a fix for active leakage.)

## Local verification

- βœ“ agent-line-budget passes (swe 23, pr-reviewer 28; cap 30)
@ZaxShen ZaxShen merged commit 5835532 into dev Apr 26, 2026
5 checks passed
@ZaxShen ZaxShen deleted the refactor/claude-md-verify-context-doctrine branch April 26, 2026 22:58
ZaxShen added a commit that referenced this pull request Apr 26, 2026
* πŸ› fix(claude.md): context-check is DB-first, codebase-on-demand

The verify-context doctrine in PR #130 listed sources as
'codebase β†’ DB β†’ web β†’ training fallback'. User caught the design
violation: bro should NOT ad-hoc-browse the codebase. The DB IS the
indexed state of the codebase.

Corrected priority + state-aware branching:

1. **Query DB first** β€” file_registry, ledger, discussions, tasks
2. **Git clean** β†’ trust the DB index, no codebase browsing
3. **Git dirty** β†’ diff against DB index; Read/Glob/Grep only on changed
   files
4. **Onboarding existing repo / post-system-design** β†’ run
   tmb_project-prescan + (optional) tmb_refresh-architecture to
   populate / refresh the index. Scan skills are the canonical entry
   to codebase indexing β€” never ad-hoc.
5. **Web** for upstream specs / standards
6. **Training fallback** last, flagged

CLAUDE.md: 103 β†’ 109 lines (+6 β€” accuracy beats brevity here).

* 🏷️ fix(claude.md): rename DB β†’ trajectory DB, disambiguate from user's project DB

User caught: 'DB here is too vague. This is the word between you and me.
What if user project also have DB?'

Renamed every bare 'DB' in CLAUDE.md to 'trajectory DB' with a one-time
clarifying clause on first use:

  The TMB trajectory DB (the SQLite file owned by the MCP trajectory
  server at <project>/.claude/<plugin-name>/trajectory.db, distinct
  from any database the user's project may have)

Subsequent mentions just say 'trajectory DB' or 'trajectory DB index'.
Bro can no longer confuse the plugin's SQLite with the user's project DB.

---------

Co-authored-by: Zax Shen <ZaxShen@users.noreply.github.com>
ZaxShen added a commit that referenced this pull request May 20, 2026
Adds plugin_config key `remotes` (array of {name, provider, url}) and
integrates it into tmb_reonboard. Bro auto-detects providers via URL
pattern matching on `git remote -v`; AUQ checkbox fires only when
detection is ambiguous or no remotes are configured.

- schema.sql: seed `remotes='[]'` default
- db.ts: migrateRemotesConfig for existing DBs
- ENUMs.md: document provider enum
- tmb_reonboard: auto-detect + AUQ + persistence + conflict re-ask

Push-gate integration (gh vs glab) intentionally out of scope.
ZaxShen added a commit that referenced this pull request May 20, 2026
✨ feat(onboarding): per-remote config + auto-detect git host (#130)

See merge request trustmybot/plugin!46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant