{"number":"02","slug":"investigation-grammar","filename":"02-investigation-grammar.md","title":"Investigation Grammar","bytes":8956,"lines":252,"sha256":"09c2897a7978c1d41c81fcf16502f1c0a76614e6db5fd2ac255a304dd3795446","sections":19,"tables":3,"code_blocks":10,"href":"/v1/docs/investigation-grammar","outline":[{"anchor":"1-root-instruction","level":2,"title":"1. Root instruction","line":3,"tables":[],"code":["02.1-root-instruction.c1"]},{"anchor":"2-entity-resolution","level":2,"title":"2. Entity resolution","line":32,"tables":[],"code":["02.2-entity-resolution.c1"]},{"anchor":"competitor-selection-grammar","level":3,"title":"Competitor selection grammar","line":48,"tables":[],"code":["02.competitor-selection-grammar.c1"]},{"anchor":"3-question-grammar","level":2,"title":"3. Question grammar","line":62,"tables":[],"code":["02.3-question-grammar.c1"]},{"anchor":"4-source-plan-grammar","level":2,"title":"4. Source-plan grammar","line":83,"tables":[],"code":["02.4-source-plan-grammar.c1"]},{"anchor":"5-nine-domain-modules","level":2,"title":"5. Nine domain modules","line":106,"tables":["02.5-nine-domain-modules.t1"],"code":[]},{"anchor":"6-volumetric-decomposition","level":2,"title":"6. Volumetric decomposition","line":122,"tables":[],"code":["02.6-volumetric-decomposition.c1"]},{"anchor":"entity-alternatives","level":3,"title":"Entity alternatives","line":133,"tables":[],"code":[]},{"anchor":"asset-alternatives","level":3,"title":"Asset alternatives","line":137,"tables":[],"code":[]},{"anchor":"stakeholder-alternatives","level":3,"title":"Stakeholder alternatives","line":141,"tables":[],"code":[]},{"anchor":"journey-alternatives","level":3,"title":"Journey alternatives","line":145,"tables":[],"code":[]},{"anchor":"time-alternatives","level":3,"title":"Time alternatives","line":149,"tables":[],"code":[]},{"anchor":"7-symptom-to-hypothesis-branching","level":2,"title":"7. Symptom-to-hypothesis branching","line":153,"tables":["02.7-symptom-to-hypothesis-branching.t1"],"code":[]},{"anchor":"8-intervention-branching","level":2,"title":"8. Intervention branching","line":174,"tables":["02.8-intervention-branching.t1"],"code":[]},{"anchor":"9-elimination-record","level":2,"title":"9. Elimination record","line":188,"tables":[],"code":["02.9-elimination-record.c1"]},{"anchor":"10-immediate-authority-compression","level":2,"title":"10. Immediate-authority compression","line":210,"tables":[],"code":["02.10-immediate-authority-compression.c1"]},{"anchor":"11-unknown-handling-grammar","level":2,"title":"11. Unknown-handling grammar","line":225,"tables":[],"code":["02.11-unknown-handling-grammar.c1"]},{"anchor":"12-audit-run-state-machine","level":2,"title":"12. Audit run state machine","line":236,"tables":[],"code":["02.12-audit-run-state-machine.c1"]}],"blocks":[{"type":"heading","level":1,"text":"Investigation Grammar","anchor":"investigation-grammar","line":1},{"type":"heading","level":2,"text":"1. Root instruction","anchor":"1-root-instruction","line":3},{"type":"code","lang":"text","content":"INVESTIGATE(\n  target,\n  executive?,\n  industry,\n  geography,\n  time_window,\n  offered_services,\n  mode,\n  authorization\n)\n→ resolve\n→ plan sources\n→ collect passively\n→ normalize\n→ corroborate\n→ analyze with LAKA\n→ generate alternatives\n→ model ranges\n→ rank\n→ report\n→ prepare outreach and CRM record\n→ review","line":5,"id":"02.1-root-instruction.c1"},{"type":"paragraph","text":"Missing target fields are not permission to guess. Produce an intake checklist and reusable research plan.","line":30},{"type":"heading","level":2,"text":"2. Entity resolution","anchor":"2-entity-resolution","line":32},{"type":"code","lang":"ebnf","content":"Organization = LegalName, TradingNames, CanonicalDomain,\n               [ RegistryID ], [ Ticker ], [ Parent ], [ Subsidiaries ],\n               Headquarters, OperatingRegions ;\n\nExecutive    = PublicName, PublicRole, OrganizationLink,\n               EffectiveDates, PublicBusinessSources ;\n\nCompetitor   = Organization, ComparisonReason, SimilarityDimensions,\n               InclusionEvidence ;","line":34,"id":"02.2-entity-resolution.c1"},{"type":"paragraph","text":"Resolve the company before collecting. Match at least two of domain, legal name, registry identifier, headquarters, ticker, or official profile. For a named person, match the role and company using official or reputable public business sources. Do not merge people on name alone.","line":46},{"type":"heading","level":3,"text":"Competitor selection grammar","anchor":"competitor-selection-grammar","line":48},{"type":"code","lang":"text","content":"Candidate pool = direct substitutes\n               | same customer/job-to-be-done\n               | same geography/price band\n               | adjacent entrants with plausible substitution\n\nUp to three primary comparators = maximize comparability across:\n  customer + offer + geography + scale + channel + business model","line":50,"id":"02.competitor-selection-grammar.c1"},{"type":"paragraph","text":"If three firms are not truly comparable, disclose the mismatch and use fewer. Archetypes are optional labels/diversity aids, not a quota; three genuine direct rivals may all be selected.","line":60},{"type":"heading","level":2,"text":"3. Question grammar","anchor":"3-question-grammar","line":62},{"type":"paragraph","text":"Every research question contains:","line":64},{"type":"code","lang":"yaml","content":"question_id: Q-0001\ndecision_supported: \"\"\nsubject: \"\"\nproperty_or_relationship: \"\"\ntime_window: \"\"\ngeography: \"\"\ncomparison: \"baseline|competitor|prior period|benchmark|none\"\nclaim_threshold: \"\"\ndisconfirming_evidence: \"\"\nallowed_sources: []\nexcluded_methods: []\nstop_condition: \"\"","line":66,"id":"02.3-question-grammar.c1"},{"type":"paragraph","text":"Good questions can be falsified. Replace “Does the company have bad PR?” with “Within the declared 12-month window, what complaint themes recur across at least two independent source types, and how did company responses differ?”","line":81},{"type":"heading","level":2,"text":"4. Source-plan grammar","anchor":"4-source-plan-grammar","line":83},{"type":"code","lang":"text","content":"Question\n→ preferred primary sources\n→ independent corroboration\n→ historical comparison\n→ competitor equivalent\n→ missing-evidence route\n→ stop rule","line":85,"id":"02.4-source-plan-grammar.c1"},{"type":"paragraph","text":"Source order:","line":95},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"government, regulator, court, standards body, official registry;","depth":0,"checked":null},{"text":"company-controlled source, filing, status page, repository, published policy;","depth":0,"checked":null},{"text":"platform-provided transparency source or first-party review record;","depth":0,"checked":null},{"text":"reputable reporting, trade publication, or research organization;","depth":0,"checked":null},{"text":"public community discussion or user-generated review;","depth":0,"checked":null},{"text":"aggregator/snippet used only as a lead to the original.","depth":0,"checked":null}],"line":97},{"type":"paragraph","text":"Company-controlled sources are authoritative about what the company publicly claims, not proof that the claim is true.","line":104},{"type":"heading","level":2,"text":"5. Nine domain modules","anchor":"5-nine-domain-modules","line":106},{"type":"table","headers":["Code","Module","Unit of analysis"],"align":["left","left","left"],"rows":[["P1","Technical and passive OSINT","public asset, configuration signal, dependency, document, change"],["P2","PR, reputation, narrative","mention, story, review, theme, response, outlet"],["P3","Marketing and demand","creative, keyword/topic, content item, journey step, conversion signal"],["P4","Blind spots and assets","unused channel, audience, content, data, partnership, region, offer"],["P5","Microeconomics","unit, price, volume, variable cost, acquisition, retention, capacity"],["P6","Competitors","like-for-like feature, offer, narrative, channel, performance proxy"],["P7","Macroeconomics","external driver, exposure path, lag, leading indicator, scenario"],["P8","Financial impact","gap, mechanism, inputs, range, attribution, timing, confidence"],["P9","Authority and CRM","relevant finding, offer match, decision-maker, compliant contact route"]],"line":108,"id":"02.5-nine-domain-modules.t1"},{"type":"paragraph","text":"Each module uses the same evidence and LAKA grammar. This makes cross-domain findings comparable.","line":120},{"type":"heading","level":2,"text":"6. Volumetric decomposition","anchor":"6-volumetric-decomposition","line":122},{"type":"paragraph","text":"For each material signal, expand across these dimensions:","line":124},{"type":"code","lang":"text","content":"Entity × Asset × Stakeholder × Journey Stage × Channel × Geography\n× Time × Event × Narrative × Metric × Source Type × Evidence State","line":126,"id":"02.6-volumetric-decomposition.c1"},{"type":"paragraph","text":"Then apply the ten internal variables and five change states. Use all fourteen change variables on signals that could affect the recommendation or dollar model.","line":131},{"type":"heading","level":3,"text":"Entity alternatives","anchor":"entity-alternatives","line":133},{"type":"paragraph","text":"`parent | subsidiary | brand | product | location | executive | board | employee role | customer segment | partner | supplier | investor | regulator | association | competitor`","line":135},{"type":"heading","level":3,"text":"Asset alternatives","anchor":"asset-alternatives","line":137},{"type":"paragraph","text":"`domain | site | app | API | repository | document | dataset | ad | landing page | email flow | review profile | listing | press room | event | patent/trademark | policy | price | offer | job post | status page`","line":139},{"type":"heading","level":3,"text":"Stakeholder alternatives","anchor":"stakeholder-alternatives","line":141},{"type":"paragraph","text":"`buyer | user | champion | approver | blocker | employee | applicant | partner | vendor | regulator | investor | journalist | community`","line":143},{"type":"heading","level":3,"text":"Journey alternatives","anchor":"journey-alternatives","line":145},{"type":"paragraph","text":"`unaware | problem-aware | solution-aware | comparison | evaluation | purchase | onboarding | adoption | support | renewal | expansion | advocacy | exit`","line":147},{"type":"heading","level":3,"text":"Time alternatives","anchor":"time-alternatives","line":149},{"type":"paragraph","text":"`current snapshot | prior snapshot | pre-event | event | post-event | seasonal | launch cycle | reporting period | rolling trend | leading indicator | lagging outcome`","line":151},{"type":"heading","level":2,"text":"7. Symptom-to-hypothesis branching","anchor":"7-symptom-to-hypothesis-branching","line":153},{"type":"paragraph","text":"Never jump from signal to diagnosis. Generate at least these hypothesis families:","line":155},{"type":"table","headers":["Family","Example explanation"],"align":["left","left"],"rows":[["Measurement artifact","collection bias, missing pages, source outage, changed taxonomy"],["Demand","intent shifted, segment changed, seasonality, category decline/growth"],["Offer","value proposition, packaging, pricing, proof, differentiation"],["Acquisition","targeting, creative fatigue, channel mix, discoverability"],["Conversion","message match, trust, usability, accessibility, latency, form friction"],["Retention","activation, value realization, support, product reliability"],["Operations","manual work, queue, ownership, capacity, vendor dependency"],["Technology","architecture, performance, observability, integration, technical debt"],["Reputation","service failure, expectation gap, narrative vacuum, slow response"],["Competitive","entrant, imitation, bundling, distribution advantage, switching"],["Macro","rates, inflation, labor, regulation, currency, supply chain"],["Intentional strategy","premium positioning, controlled demand, channel exit, focus"]],"line":157,"id":"02.7-symptom-to-hypothesis-branching.t1"},{"type":"paragraph","text":"Actively seek evidence that the apparent “gap” is intentional or immaterial.","line":172},{"type":"heading","level":2,"text":"8. Intervention branching","anchor":"8-intervention-branching","line":174},{"type":"paragraph","text":"For each preferred hypothesis, generate state-distinct alternatives:","line":176},{"type":"table","headers":["Change state","Intervention pattern"],"align":["left","left"],"rows":[["C0","observe, preserve, benchmark, instrument"],["C1","clarify, tune, repair, add one missing control, run one test"],["C2","coordinate campaign/process redesign, integrate tools, repackage offer"],["C3","change architecture, operating model, governance, incentives, data loop"],["C4","redefine category, beneficiary, unit of value, delivery model, or demand curve"]],"line":178,"id":"02.8-intervention-branching.t1"},{"type":"paragraph","text":"Also generate `do nothing`, `defer until trigger`, `buy`, `build`, `partner`, and `stop/retire` where relevant.","line":186},{"type":"heading","level":2,"text":"9. Elimination record","anchor":"9-elimination-record","line":188},{"type":"code","lang":"yaml","content":"option_id: OPT-0001\nmechanism: \"\"\nchange_state: C0|C1|C2|C3|C4\nevidence_fit: 0-5\nstrategic_fit: 0-5\nurgency: 0-5\nreversibility: 0-5\ncapacity_fit: 0-5\ntime_to_useful_evidence: \"\"\nestimated_cost_range: [low, base, high]\nestimated_value_range: [low, base, high]\nrisk: 0-5\ndependencies: []\ndecision: keep|defer|discard|needs-data\nreason: \"\"","line":190,"id":"02.9-elimination-record.c1"},{"type":"paragraph","text":"Do not discard a high-value structural option merely because it is slow; route it to a portfolio horizon while selecting a smaller near-term test.","line":208},{"type":"heading","level":2,"text":"10. Immediate-authority compression","anchor":"10-immediate-authority-compression","line":210},{"type":"paragraph","text":"The full research volume is compressed into:","line":212},{"type":"code","lang":"text","content":"One decision-maker\n+ One public business priority\n+ One non-obvious evidence chain\n+ One bounded economic mechanism\n+ One reversible diagnostic or intervention\n+ One permission-based CTA","line":214,"id":"02.10-immediate-authority-compression.c1"},{"type":"paragraph","text":"The outreach message must not expose the full surveillance trail. Use the minimum relevant evidence and link to public sources when helpful.","line":223},{"type":"heading","level":2,"text":"11. Unknown-handling grammar","anchor":"11-unknown-handling-grammar","line":225},{"type":"code","lang":"text","content":"Unknown(input)\n→ state why it matters\n→ identify lawful source or question that could resolve it\n→ show which conclusions depend on it\n→ keep model as range or not estimable\n→ never fill with an uncited benchmark silently","line":227,"id":"02.11-unknown-handling-grammar.c1"},{"type":"heading","level":2,"text":"12. Audit run state machine","anchor":"12-audit-run-state-machine","line":236},{"type":"code","lang":"text","content":"DRAFT_SCOPE\n→ RESOLVED_TARGET\n→ APPROVED_SOURCE_PLAN\n→ COLLECTING\n→ NORMALIZING\n→ ANALYZING\n→ HUMAN_REVIEW\n→ REPORT_READY\n→ OUTREACH_READY\n→ ARCHIVED_OR_MONITORED","line":238,"id":"02.12-audit-run-state-machine.c1"},{"type":"paragraph","text":"Any policy, privacy, identity, or evidence failure moves the run to `BLOCKED_REVIEW`.","line":251}]}