Resolve Before Asking

Resolve Before Asking — Exhaust the Brain Before Bothering the User

Convention: see conventions/brain-first.md for the base lookup chain (search → query → get_page → external APIs). This skill extends that chain one hop further, to the human boundary: asking the user is the LAST resort, after the brain AND external escalation, not a shortcut around them.

Convention: see _brain-filing-rules.md — pages touched by the ingest-resolution section file by primary subject (people/, companies/).

Purpose

Never ask the user "who is X?" when the answer already exists in the brain.

The memory answers before the human is bothered — that is the product promise. This skill defines the lookup chain that runs before any entity-identification question is sent to the user, and the escalation format when asking really is justified.

The Bug This Kills

The pattern: the agent encounters an entity with a rich brain page — timeline entries, meeting history, an imported message archive — and instead of reading them, asks the user "who is X?". This is lazy escalation. It spends the user's attention on questions the system can answer itself.

Examples of the bug (anonymized):

• alice-example — her brain page already carried a role line ("Chief of Staff at acme-example") and a long meeting history → the agent still asked.
• charlie-example — a thick imported email thread whose subject lines all pointed at one shared project → the agent still asked.

When This Fires

This is a harness-routing convention, not a mechanical guarantee: route here whenever ANY of these are true —

1. A reply draft contains "who is [name]?" or equivalent.
2. A draft asks about someone's role, relationship, or identity.
3. You are about to present an entity as "unknown" or "unidentified".
4. A brain page has [To be filled by content analysis] or similar placeholder text.
5. You are composing a list of people and leaving any as "unknown relationship".

The Lookup Chain (run in order; STOP at the first clear answer)

Step 1: think — cross-brain synthesis (solves most cases)

gbrain think "Who is {entity}? What is their relationship to the user? What role do they play? Use all available context — meetings, timeline, imported archives, facts."

think synthesizes across ALL brain data. If the entity has a page with imported-activity stats, timeline entries, and meeting history, think will connect the dots. Over MCP, entity("{entity}") first gives a zero-LLM card (aliases, last-touched, top edges); synthesize is the heavy cross-page answer when the card isn't enough.

If this returns a clear answer → STOP. Use the answer. Do not ask the user.

Step 2: search + full page read

gbrain search "{entity}" --limit 5
gbrain get {entity-slug}

What to look for:

• relationship field in frontmatter — filled means resolved.
• Role signals repeated in timeline entries ("advisor", "colleague at acme-example", "chief of staff").
• Facts table — any role/relationship facts.
• Meeting history — what did they attend? With whom?

If timeline entries repeat a consistent role → STOP. The role is obvious. Do not ask the user.

Step 3: Query each mounted source the brain actually has

Don't hardcode channels. Check what the brain holds, then query it:

gbrain sources list
gbrain query "emails with {entity}" --limit 10
gbrain query "meetings with {entity}" --limit 5

Whatever is mounted — an email archive, calendar imports, chat transcripts, meeting notes — a handful of subject lines or meeting titles usually reveals the relationship:

• Invoice / scheduling / billing subjects → professional services.
• Recurring 1:1 titles with consistent co-attendees → colleague.
• Dinner / weekend-plan messages → personal friend.

Step 4: Timeline + graph walk

gbrain timeline {entity-slug} --limit 20
gbrain backlinks {entity-slug}
gbrain graph {entity-slug} --depth 2

Dated events, who references this entity, and what it connects to. A person who back-links from a company page and three meeting pages is not an unknown.

Step 5: Web search (external escalation, per brain-first)

Only after steps 1–4 return nothing useful. Run a generic web search on "{entity name} {company/domain hints accumulated in steps 1-4}". Fold anything found back into the brain page before using it (the brain-ops read-enrich-write cycle), so the next lookup doesn't repeat the work.

Step 6: Escalate to the user (LAST RESORT) — ask WITH a hypothesis

Only after ALL previous steps return nothing conclusive:

• State what you searched.
• State what you found — even partial signals.
• Ask a SPECIFIC, confirmable question: not "who is X?" but "Is {entity} the {best guess assembled from partial signals}?"

Use ask-user for the choice-gate mechanics (2–4 options, escape hatch, stop the turn).

Confidence Thresholds

• High confidence (don't ask): think/synthesize gives a clear answer, OR 3+ timeline entries carry a consistent role description, OR the page's relationship field is filled.
• Low confidence (ask, leading with your best guess): contradictory signals or very sparse data. Ask — but the question opens with your hypothesis, and states the contradiction if there is one.

There is no third state. Either the brain answered (use it) or it didn't (finish the chain, then ask with a hypothesis).

No Placeholders at Ingest

When ANY ingestion pipeline (email import, calendar enrichment, chat transcripts, meeting ingestion) creates or significantly updates a person or company page, resolve the entity's identity and relationship immediately — never leave placeholder text. Pages like

• [To be filled by content analysis]
• > Contact from the user's personal network.
• an empty ## Context section

are bugs, especially when the ingestion batch itself contains hundreds of signals about who the person is. Run this as a post-ingestion pass over every page the batch created or updated:

1. Check for placeholders. Scan the touched pages for markers ([To be filled, Unknown relationship, TBD). No placeholders AND relationship filled → skip, already resolved.
2. Run the chain (steps 1–4 above; at ingest time, step 1 alone usually suffices because the batch just wrote the signals think needs).
3. Extract: relationship type (friend / colleague / advisor / family / founder), professional role (title + company), key context (how they know the user, what era).
4. Update the page (put_page): fill the relationship frontmatter field, replace the placeholder description with a real one-liner, update the ## Context or intro paragraph.
5. Batch efficiency for bulk runs (100+ pages): resolve in batches of 10–20; prioritize by captured-activity volume (more activity = more likely the user meets this name in a briefing); skip pages already substantive.

Email-domain shortcut (hypothesis generator, not proof)

Before running the chain, the sender's domain often seeds the hypothesis: