dossier

Dossier — Decision-Grade Entity Research

Portability: Requires WebSearch + WebFetch, Node.js with docx package, and optionally bash_tool + curl for free APIs (SEC EDGAR, GitHub, ProPublica). BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) are optional enhancements. Works in Claude Code CLI natively.

Non-Generic Framing — The Differentiator

This skill is decision-grade entity research with hypothesis-testing. It refuses to be "tell me about Microsoft". Every invocation forces the user to expose their hypothesis upfront (Q4) so the dossier tests it rather than confirms it.

The use case shape:

"I'm pitching Microsoft Tuesday. My hypothesis is they're consolidating AI spend on their first-party Foundry platform. Validate or disprove, and give me three conversation hooks tied to what you find."

NOT:

"Tell me about Microsoft."

The forcing Q4 — the hypothesis question — is the non-generic anchor. Skip it and the skill produces a Wikipedia summary.

See references/hypothesis_testing_discipline.md for the canon.

Agent Integrity Rules (Research-Pack Convention)

Locked verbatim per PR #657 audit.

• Execution discipline. Sequential search calls. WebSearch + WebFetch have looser rate limits than Consensus but still apply 1 q/sec etiquette. Confirm response received before next call.
• Source discipline. Cite only sources returned by this session's tool calls. Wikipedia / training knowledge labeled [Background — verify before quoting] and excluded from primary findings count.
• Three-count tracking. Queries sent / sources received / sources cited. Plus per-tier breakdown (primary / secondary / tertiary) unique to dossier. Surfaced in audit log.
• Retry policy. On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user.
• Source reliability tier. Each citation tagged primary (official, SEC, court records) / secondary (mainstream news, trade press) / tertiary (blogs, forums). DOCX surfaces tier on every flag.

Phase 1: Grill-Me Intake (6 forcing questions, one at a time)

Q1 (root) — Subject identity

Who is the subject? Give me the exact name and, if a company, the website or LinkedIn URL. If a person, their LinkedIn URL or a unique identifier (company affiliation + role).

Why I'm asking: Disambiguation. There are 47 John Smiths. There are three companies called "Atlas". I need a specific entity to research.

If user gives only a name, push for a second identifier. Refuse to proceed on ambiguous names.

Q2 (depends on Q1) — Subject type

What kind of subject is this? Pick one: person / company / nonprofit / government org / other.

Why I'm asking: Different source matrices apply. For people I check LinkedIn, GitHub, Scholar, news; for companies I check SEC EDGAR (if public), Crunchbase, news, GitHub for tech orgs; for nonprofits I check Form 990s on ProPublica.

Forcing choice. "Other" requires a one-line description.

Q3 (depends on Q2) — Purpose

What are you preparing for? Pick one:

1. Sales meeting / partnership pitch
2. Investment diligence
3. Acquisition diligence
4. Journalism / due diligence
5. Job interview prep
6. Competitive intelligence
7. Personal vetting (date, hire, business partner)
8. Other (specify)

Why I'm asking: The purpose dictates the angle, the depth, and the red-flag sensitivity. Sales prep needs conversation hooks. Investment diligence needs traction signals. Personal vetting needs careful sensitivity boundaries.

Q4 (depends on Q3) — Hypothesis — MANDATORY

What's your hypothesis going in? What do you already believe about this subject, and what do you want to verify or disprove?

Why I'm asking: This is the critical question. A dossier that just confirms what you already think is worthless. By stating your hypothesis upfront, I can search for evidence that would disprove it as well as evidence that supports it — and give you a verdict you can actually use.

Examples:

• "I believe Microsoft is consolidating AI spend on first-party Foundry. Verify or disprove."
• "I think the CEO is over their head — too much TAM talk, no traction. Test that."
• "I believe this nonprofit's overhead ratio is sketchy. Check the 990s."
• "I think this person is technical enough to handle a CTO role. Verify."

MANDATORY. If user says "I don't have one", push back once: "Then guess. Commit to a position you can update later. The dossier needs a hypothesis to test, otherwise it's a generic profile and won't help you make a decision."

If still refused: fall back to implicit hypothesis "what's the most surprising thing I could find?" and flag the fallback in audit log.

This question is the non-generic anchor. Skip it and the skill becomes a Wikipedia summary.

Q5 (depends on Q3) — Depth

Time horizon: 5-minute brief or 15-minute decision-grade dossier?

Why I'm asking: Brief mode caps at ~10 searches and skips the network + reputation passes. Decision-grade goes deeper on every section. Pick based on how much skin you have in this decision.

Forcing choice.

Q6 (asked only if Q3 ∈ {journalism, personal vetting}) — Sensitivities

Anything sensitive to exclude? E.g., personal medical, family details, political history, or specific topics off-limits?

Why I'm asking: Some research contexts have ethical constraints. I'd rather know upfront than surface something you'd never share.

Skip for sales/investment/acquisition/competitive intel (low sensitivity); ask for journalism/personal vetting (high sensitivity).

Stop condition: After Q6 (or earlier with dependency skips), commit and start Phase 2. Never re-open intake after Phase 2 begins.

Phase 2: Subject Disambiguation

Before Phase 3, resolve the subject to a specific entity:

• For people: confirm LinkedIn URL OR (employer + role + city)
• For companies: confirm domain OR (legal name + incorporation jurisdiction)
• For nonprofits: confirm EIN OR (legal name + state)
• For government orgs: confirm official .gov URL

If still ambiguous after Q1 push-back: halt and re-ask Q1 with disambiguating identifiers. Refuse to proceed.

Phase 3: Source Matrix Selection

Routed by Q2 subject type. See references/subject_type_source_matrix.md for the full canon.

Person

• LinkedIn (manual fetch or LinkedIn MCP if BYOK)
• Personal website
• Twitter/X (rate-limited; degrade gracefully)
• GitHub (if technical subject)
• Google Scholar (if academic)
• News (WebSearch + WebFetch)
• Conference talk transcripts, podcasts (WebSearch)

Company

• Official website (about, leadership, news, careers)
• SEC EDGAR (free API; 10-Ks, 10-Qs, 8-Ks for public co's)
• Crunchbase free tier (or Crunchbase MCP if BYOK)
• News (WebSearch + WebFetch)
• GitHub (for tech orgs)
• Glassdoor + Comparably (sentiment; degrade gracefully if scraping blocked)
• LinkedIn company page

Nonprofit

• ProPublica Nonprofit Explorer (free; Form 990s)
• Official website
• News
• GuideStar (if accessible)

Government org

• Official .gov sites
• News
• ProPublica (for federal agencies)

If a paid MCP is connected (Apollo, Pitchbook, SimilarWeb), use it but mark findings as BYOK-sourced in the audit log.

Phase 4: Hypothesis-Driven Search

Every Phase 4 search MUST be classified as either:

• Supporting evidence (confirms hypothesis), OR
• Disconfirming evidence (would refute hypothesis)

≥30% of search budget allocated to disconfirming queries. Enforced via scripts/disconfirming_evidence_balance.py.

Example for hypothesis "Microsoft is consolidating AI spend on Foundry":

• Supporting: "Microsoft Foundry adoption 2026", "Microsoft AI infrastructure consolidation"
• Disconfirming: "Microsoft OpenAI deal renegotiation", "Microsoft AI vendor diversification", "Microsoft third-party model partnerships 2026"

This is what makes the dossier decision-grade rather than confirmation-biased.

For each search:

• Record via citation_tracker.py with classification (supporting / disconfirming)
• Apply source tier from source_tier_classifier.py to each result URL

Phase 5: 12-Month Activity Timeline

Default 12-month window for activity timeline; deeper for foundational identity.

Categories:

• News (acquisitions, hires, departures, product launches)
• Funding rounds / financial events
• Controversies / legal events
• Public statements / strategy shifts

Reverse chronological. Each entry hyperlinked + tiered.

Phase 6: Network + Reputation Signals

Network

• Companies: investors (in/out), customers (named), partners
• People: co-founders, advisors, mentors, employers, board roles
• Nonprofits: funders, board, leadership

5-10 entries, ranked by relevance to hypothesis.

Reputation

• Sentiment from news (recent 12 months)
• Glassdoor for companies (overall rating + 3 representative reviews)
• Peer mentions for people
• Caveat: reputation data is noisy; tier accordingly

Phase 7: Red-Flag Pass

Surface but don't sensationalize:

• Litigation (court records → primary tier)
• Regulatory actions (SEC, DOJ, agency actions → primary)
• Unusual departures (key personnel exits within 90 days)
• Financial signals (going-concern notes in 10-Ks → primary)
• Reputation hits (sustained negative coverage → secondary)

Each flag tiered. Tier shows up next to every flag in the DOCX.

Phase 8: Conversation Hook Generation

3-5 specific hooks tied to actual findings, not generic talking points.

See references/conversation_hook_quality.md for the canon.

❌ Generic	✅ Finding-tied
"Ask about their roadmap"	"Mention their recent acquisition of [X] — it signals they're investing in vertical Y. Suggested framing: 'Saw the [X] announcement — how does that change your roadmap on Y?'"
"Ask about hiring"	"Their VP Engineering left 3 weeks ago (LinkedIn). Suggested framing: 'I noticed [name] moved on — what's the eng leadership plan?'"
"Talk about their values"	"They updated their pricing page last week (their official site). Suggested framing: 'Saw the pricing refresh — what drove that?'"

Each hook:

• The hook (one sentence)
• The finding it's tied to (with hyperlink + tier)
• Suggested framing (verbatim phrasing user can adapt)

Phase 9: DOCX Generation (9 Sections)

Via Node.js + docx library.

1. Executive Summary — one paragraph: who they are + why they matter + verdict on the hypothesis (SUPPORTED / PARTIALLY SUPPORTED / DISPROVEN / INCONCLUSIVE) + 3 things-you-should-know bullets.
2. Identity Facts Table — founded/born, location, size/stage, current role, key affiliations. All cells sourced; hover-text tier.
3. Hypothesis Test — user's hypothesis stated verbatim. Supporting evidence (3-5 bullets with hyperlinked citations). Disconfirming evidence (3-5 bullets with hyperlinked citations). Verdict paragraph (2-3 sentences explaining the weight).
4. 12-Month Activity Timeline — News, funding, hires, departures, product launches, controversies. Reverse chronological. Each entry hyperlinked.
5. Network Signals — Collaborators / investors / associates. 5-10 entries, ranked by relevance to hypothesis.
6. Reputation Signals — Sentiment from news, Glassdoor for companies, peer mentions for people. Caveat: reputation data is noisy.
7. Red Flags + Hidden Patterns — Litigation, regulatory actions, unusual departures, financial signals, reputation hits. Tiered.
8. Conversation Hooks — 3-5 specific hooks tied to findings. Each: hook + finding + suggested framing.
9. Source Provenance + Audit Log — Per-source list with tier. Search summary table (#, query, classification, sources returned, sources cited). Three counts + per-tier counts. Failed searches. BYOK-MCP usage flag.

Styling

Arial 12pt body, navy headings (#1a3a5c), light blue table headers (#e8f0f8), red red-flag callout, green conversation-hook callout.

Hyperlink patterns

new ExternalHyperlink({
  link: "https://...",
  children: [new TextRun({ text: title, style: "Hyperlink" })],
});

Phase 10: Deliver

• Save: <output-dir>/dossier_<entity-slug>_<YYYY-MM-DD>.docx
• Chat summary: file path + verdict on hypothesis + audit counts + tier breakdown + BYOK MCPs used (if any)
• Validate: python scripts/office/validate.py <docx>

Tooling

Script	Role
scripts/citation_tracker.py	Three-count audit + supporting/disconfirming classification + source-tier tagging at ~/.dossier_sessions/<session>.json
scripts/disconfirming_evidence_balance.py	Verifies ≥30% of search budget allocated to disconfirming queries; warns if biased
scripts/source_tier_classifier.py	URL → primary / secondary / tertiary classification via domain heuristics

References

• references/hypothesis_testing_discipline.md — ≥30% rule + decision-grade vs encyclopedic (7+ sources)
• references/subject_type_source_matrix.md — person/company/nonprofit/gov source matrices (7+ sources)
• references/conversation_hook_quality.md — finding-tied hook discipline (7+ sources)

Error Handling

Failure	Behavior
Subject name ambiguous	Refuse to proceed. Re-ask Q1 with disambiguating identifier.
User refuses to state hypothesis	Push back once. If still refused, fall back to "what's the most surprising thing I could find?" implicit hypothesis. Flag in audit.
Subject has zero public footprint	Surface explicitly. Suggest different name or early-stage. Don't fabricate.
LinkedIn scrape blocked	Note in audit; fall back to WebSearch; suggest user verify manually.
SEC EDGAR fails	Retry once. If still failing, note "public filings not retrieved" and continue.
Sentiment data sparse	Mark reputation section as "limited public signal"; don't infer from training.
Sensitive topic surfaces (Q6 exclusion)	Exclude from DOCX. Note in chat (not in DOCX) so user knows the exclusion was honored.
3 consecutive tool failures	Stop, alert user, share collected so far.
DOCX generation fails	Save raw data as JSON fallback.

Anti-Patterns To Reject

• Producing a dossier without forcing Q4 hypothesis
• Allocating <30% of search budget to disconfirming evidence
• Batching intake questions
• Accepting ambiguous subject names
• Generic conversation hooks ("ask about their roadmap")
• Sensationalizing red flags (tier them, don't editorialize)
• Skipping the source-reliability tier on flags
• Fabricating coverage when LinkedIn or scraping is blocked
• Using BYOK-MCP data without flagging in audit log
• Including sensitive topics user excluded in Q6
• Confirmation-biased verdict ("SUPPORTED" without engaging with disconfirming evidence)

---

Version: 1.0.0 Source spec: megaprompts/12-dossier-megaprompt.md Build pattern: Path B (direct conversion). Research-pack sibling, hypothesis-testing variant.