lemma-research

name

lemma-research

description

Run rigorous, source-backed research in an existing Lemma pod. Use for investigations, literature or market scans, policy and product research, fact-checking, comparisons, current-information questions, and updates to prior research that require pod files, workspace material, or web sources; exact citations; explicit freshness and conflict handling; and a durable memo, evidence ledger, or source pack published to /me or an authorized shared pod folder.

Lemma Research

Build an auditable investigation, not a disposable answer. Preserve the path from question to source to evidence to claim, then publish the useful result into the pod when the task authorizes a durable artifact.

For any multi-source investigation, read references/investigation-format.md before collecting evidence. Use its stable IDs, ledger fields, citation forms, and memo structure.

Operating contract

• Ground every material factual claim in inspected evidence. Treat search-result snippets, filenames, summaries, and model memory as leads, not evidence.
• Separate source (S##), evidence (E##), and claim (C##). Preserve the distinction even in a short answer.
• Prefer pod-local context before external context when researching the user's organization, history, or prior work. Do not assume the public web supersedes private canonical material.
• Act only as the current user. Respect pod membership, workload grants, RLS, and file visibility. A delegated agent uses the invoking user's RLS scope and /me; it gains no service-account or admin view.
• Treat an empty result as "not visible or not found in this scope," not proof that the information does not exist. Never bypass RLS or a missing grant.
• Keep observable research records, not hidden chain-of-thought. Record queries, sources, evidence, decisions, conflicts, and unknowns; omit private reasoning traces.
• Use current CLI help or the lemma-user skill if a command differs. Never improvise a Lemma command or path.

1. Frame the investigation

Orient to the active pod and its existing knowledge layout:

lemma pods describe
lemma files ls /

Write a compact research contract before searching:

1. State the decision or question the result must support.
2. Define the subject, population, geography, time window, comparison set, and ambiguous terms.
3. State what is out of scope and what deliverable is expected.
4. Decompose the question into answerable subquestions. Classify each as factual, comparative, causal, interpretive, or forward-looking so the evidence standard matches the claim.
5. Identify the claims that would change the conclusion, plus the strongest plausible counterclaim for each.
6. Set an as_of date and a stopping rule: stop when decisive claims have adequate support, credible contradictions are resolved or exposed, and remaining unknowns are explicit.

Do not silently broaden the task. Ask only when a missing choice would materially change the research; otherwise state the narrow assumption and proceed.

For an update to prior research, locate the existing brief, source register, evidence ledger, and memo first. Preserve stable IDs, add new source versions, mark superseded or stale claims, and report the delta instead of silently replacing the earlier record.

2. Design the source strategy

Map every subquestion to its best available evidence, required freshness, and a fallback source. Match source type to claim type instead of applying one universal ranking.

Use this order where relevant:

1. Inspect user-provided and pod sources for the user's facts, prior decisions, terminology, and internal state.
2. Inspect in-scope workspace files for implementation truth, datasets, logs, and authored material.
3. Search the web for current or external facts, beginning with original records, official documentation, first-party data, standards, filings, or research.
4. Use reputable secondary sources for discovery, interpretation, and independent corroboration.
5. Search deliberately for disconfirming evidence, superseding versions, and definitions that could make apparently similar numbers incomparable.

Do not count duplicated reporting as independent corroboration. Trace syndication and citations back to the originating source where possible.

3. Retrieve and inspect sources

Pod files

Search narrowly, then open the exact passage:

lemma files search "target concept" --scope /knowledge
lemma files search "exact phrase" --scope /knowledge --method TEXT
lemma files cat /knowledge/source.pdf --pages 3-7
lemma files cat /me/notes/context.md --lines 20-80

Use HYBRID search by default; use TEXT for exact names, identifiers, and quoted phrases, and VECTOR for conceptual recall. Vary queries and scoped folders rather than trusting one ranked result. Record the path and returned page or line range.

Inspect a chart, scan, signature, footnote, table, or layout visually instead of inferring it from extracted text:

lemma files children /knowledge/source.pdf
lemma files child /knowledge/source.pdf/pages/page_0003.jpg ./source-p3.jpg

Then view ./source-p3.jpg with the available image-viewing capability. Use lemma files cat ... --pages 3 for what the page says and the rendered page image for what it shows. Prefer the pod's converted markdown and page images; use liteparse-documents only for outside-pod documents or when the derived artifacts are missing or insufficient.

Remember that CSV, JSON, XLSX, images, and email files are stored but not indexed. Only successfully processed, search-enabled documents with extracted chunks appear in search; a stored non-indexed file does not appear by filename alone. Check lemma files stat <path>, then list or download known files instead of concluding that search found everything.

Workspace files

Inventory before reading broadly:

rg --files ./path/to/in-scope-material
rg -n "target term" ./path/to/in-scope-material

Use repository files, schemas, tests, logs, and history as direct evidence only for what they actually establish. Record an absolute or repository-relative path plus line, symbol, revision, or timestamp. Do not upload private workspace material to a shared pod folder unless the task authorizes that audience.

Web sources

Discover sources with your own web search — phrase the query specifically, with a date or a domain, rather than broadly. There is no CLI search command: search is a capability you already have, and the CLI's wrapper around it was removed.

Open promising results and inspect the source itself. Use the browser for JavaScript-rendered pages, authentication, tables, or navigation. Preserve a decisive or volatile page when the investigation needs a durable snapshot:

save-webpage https://example.com/source --formats markdown,pdf --out research

Record the canonical URL, publisher, publication or effective date, version, and retrieval date. Do not cite a search snippet, an inaccessible page, or a generated summary as though the underlying source was verified.

4. Build the evidence ledger while reading

Create source, evidence, and claim records as facts are inspected; never reconstruct the ledger from memory after writing the conclusion.

• Assign one stable S## ID per source or version.
• Assign one E## row per bounded proposition or observation. Include an exact page, section, table, timestamp, line range, or other locator.
• Assign one atomic C## claim for each proposition used in the result.
• Link every evidence row to the claims it supports, contradicts, or qualifies.
• Preserve only the minimum useful excerpt; paraphrase faithfully and keep the locator so another reader can verify it.
• Record access limits, missing pages, extraction defects, paywalls, and suspected duplication as evidence-quality notes.

Use the templates in references/investigation-format.md. Keep the ledger in Markdown for a compact investigation or CSV/JSON plus a Markdown source register when it will be filtered, updated, or consumed by an app.

5. Form claims and citations

Write claims narrowly enough to prove or disprove. Mark each as supported, contested, disproven, unknown, or stale; record confidence as high, medium, or low with a short evidence-based rationale.

• Place citations immediately after the claim they support.
• Cite exact locators: page, section, table, line, timestamp, record, or revision.
• Use direct web links for web claims and stable source IDs plus pod/workspace locators for non-web claims.
• Label calculations, synthesis, and forecasts as analysis or inference. Cite their inputs and show the material assumptions.
• Do not let a citation support a broader, more certain, or more current statement than the source establishes.
• Avoid decorative citation piles. Prefer the few sources that directly establish the claim and use independent corroboration when risk warrants it.

Run two audits before publishing: trace each material sentence backward to adequate evidence, then trace each decisive evidence item forward to the claim or conclusion that uses it.

6. Resolve freshness and conflicts

Verify time-sensitive claims against a source current to the investigation's as_of date. Distinguish publication date, event date, effective date, data period, and last-updated date. Mark a source or claim stale when the required time horizon has passed; never hide an older date behind present tense.

When sources disagree:

1. Confirm that they measure the same entity, interval, geography, unit, definition, and version.
2. Check whether one source cites, copies, corrects, or supersedes the other.
3. Prefer the more direct and current source only after confirming equivalent scope.
4. Seek an independent adjudicating source or underlying record.
5. Preserve the disagreement when it cannot be resolved. Mark the claim contested, explain the decision impact, and avoid averaging incompatible facts.

Keep "not found," "not accessible," "not measured," and "evidence of absence" as different states.

7. Synthesize the answer

Lead with the answer, decision, or finding. Then present the decisive evidence, important qualifications, credible counterevidence, and remaining unknowns. Separate observed facts, inference, and recommendation. Use a comparison table or timeline only when it exposes a real relationship.

Use the memo template in references/investigation-format.md. For a short response, retain its logic in miniature: answer, evidence, conflicts, unknowns, sources, and as_of date.

Stop when additional sources are unlikely to change the conclusion. Do not equate volume with rigor.

8. Publish and verify the durable result

Choose the destination deliberately:

• Publish private or audience-unspecified work under /me/research/<investigation-slug>/.
• Publish collaborative work only to an authorized existing shared folder such as /research/<investigation-slug>/. Remember that every path outside /me is pod-shared; there is no /pod prefix.
• Treat an agent's /me as the invoking user's private tree, never agent-private storage. If a workload receives MISSING_WORKLOAD_RESOURCE_GRANT for a shared folder, report the missing grant; do not relocate or self-elevate to bypass it.
• Skip pod writes when the user asked only for an answer and did not authorize a durable artifact. Keep the result in the response and state what could be saved.

Publish at least the memo and source register for durable work; include the evidence ledger and selected source snapshots when future verification or monitoring needs them. Adapt filenames to an established pod workflow rather than creating a parallel taxonomy.

research_slug="refund-policy-review"
lemma files mkdir /me/research
lemma files mkdir "/me/research/$research_slug"
lemma files upload ./memo.md "/me/research/$research_slug/memo.md"
lemma files upload ./sources.md "/me/research/$research_slug/sources.md"
lemma files upload ./evidence.csv "/me/research/$research_slug/evidence.csv" --no-search
lemma files stat "/me/research/$research_slug/memo.md"
lemma files cat "/me/research/$research_slug/memo.md"

Replace /me/... with the approved shared destination when required. After upload, verify the exact paths, reopen the memo, check that no content was truncated, and confirm that every cited source path or URL resolves for the intended audience. Use lemma files url <path> when a signed-in pod member needs an in-app link.

Report the published path, as_of date, confidence, unresolved gaps, and what should trigger a refresh.

Related skills

• Use lemma-user for general pod operations and current CLI semantics.
• Use browser to inspect or preserve rendered web pages.
• Use liteparse-documents for outside-pod document parsing or OCR fallback.
• Use lemma-data-analysis when the main work is quantitative validation, computation, or charting; carry its results into this skill's evidence ledger.
• Use lemma-artifact-author when the final deliverable must be a polished PDF, DOCX, spreadsheet, or slide deck; keep this skill's source and citation contract.