Keine Research

This skill produces a long-form research report grounded in the knowledge base and supplemented by web research. The output is saved as a Markdown file in reports/.

When to use this skill

Only trigger when the user explicitly asks for research, a deep dive, or a detailed report. This is not a lookup skill — it is a slow, thorough process. If the user asks a quick question, answer it directly. If they want to add something to the KB, use keine-update-entries instead.

Report location

All reports go in reports/<yyyy-mm-dd-slug>.md. This directory is separate from entries (docs/) and maps (docs/maps/). Reports are synthesis documents — they cite KB entries and web sources but are not themselves knowledge entries.

Workflow

Work through each phase in order. Do not skip ahead.

Phase 1 — Understand the question

Before touching the KB, decompose the research question:

• What is the user actually asking? Restate it precisely.
• What sub-questions or facets need to be addressed for a complete answer?
• What depth of coverage is expected? (If unclear, assume comprehensive.)

Write these sub-questions down — they become the skeleton of the report.

Phase 2 — Mine the knowledge base

Use the KB's structure to orient yourself quickly:

# Survey topic maps
ls docs/maps/

# Survey available tags
ls docs/tags/

# Search for relevant keywords
grep -ri "keyword" docs/

Read all relevant map files first — they give the fastest orientation to a topic area and link to the most relevant entries.

Then read the specific entries linked from those maps and tags. For each entry, note:

• What it covers
• Which sub-questions it answers (fully or partially)
• What it does NOT cover

Be honest about gaps. Local knowledge is almost always incomplete for a substantive research question.

Phase 3 — Web research

For each gap or unanswered sub-question identified in Phase 2, search the web. Be systematic: search each facet deliberately rather than doing a single broad search.

For each significant web finding:

• If the finding has durable value (it's not ephemeral news or trivial), create a KB entry using the keine-update-entries skill. This ensures future agents can find it.
• Track the source URL to include in the report's references, whether or not you create an entry.

Do not create entries for every result — only for knowledge worth keeping. A good rule: if a future agent researching a related question would benefit from finding this entry, create it.

After creating new entries, run tag maintenance scripts/maintain_tags.py

Phase 4 — Write the report

Write a detailed, long-form report. Inline citations ([1], [2], ...) should appear throughout the body wherever a claim is grounded in a specific source. Numbered references are listed at the end.

Aim for depth over brevity — this is not a summary. Each section should explain, not just list.

Report frontmatter

---
title: "Research Report: <topic>"
question: "<the original user question, verbatim>"
---

Report structure

# Research Report: [Topic]

## Research Question
State the exact question being answered and any clarifications about scope.

## Executive Summary
5–8 sentences capturing the key answer, major findings, and most important takeaways.
Write this last, after the full report is drafted.

## [Section per major facet or sub-question]

Detailed prose covering the facet. Use H3 subheadings for subsections.
Cite sources inline: "According to [1], ..." or "This pattern is well-documented [2][3]."

Repeat for each sub-question identified in Phase 1.

## Synthesis
How do the findings across sections connect? What is the overall picture?
What tensions, trade-offs, or unresolved debates exist?

## Gaps & Open Questions
Aspects that couldn't be fully resolved with available sources.
Questions worth pursuing in future research.

## References

### Knowledge Base Entries
- [KB-1] [Title](../relative/path/to/entry.md) — one-line description
- [KB-2] ...

### Web Sources
- [W-1] [Title or description](URL)
- [W-2] ...

Use [KB-N] for KB entries and [W-N] for web sources as inline citation keys.

Phase 5 — Save and commit

Save the report to reports/<yyyy-mm-dd-slug>.md. The slug should reflect the topic, not the date (e.g., 2026-03-11-transformer-attention-mechanisms.md).

Commit everything created in this workflow:

git add reports/<report>.md docs/ docs/tags/
git commit -m "docs(report): <topic>"

Phase 6 — Update topic map (if warranted)

If Phase 3 produced several new entries on a coherent topic, consider updating or creating a topic map using keine-update-maps. This is optional — only do it if the new entries genuinely enrich an existing map or justify a new one.

Quality bar

A good research report:

• Has inline citations throughout — claims should be traceable to sources
• Covers all sub-questions identified in Phase 1
• Is honest about what is unknown or unresolved
• Creates at least a few new KB entries from web research (unless local knowledge was already comprehensive)
• Is long enough to be genuinely useful — several hundred to a few thousand words depending on the topic

A poor report is a bullet-point summary with no citations and no new entries created. Push past the surface.