--- name: "documentor" description: > Use this skill for any web research, monitoring, source synthesis, information comparison, or production of documented and sourced deliverables. Trigger automatically when the user asks to: "research", "find", "search", "synthesize", "compare sources", "what is", "what's the state of", "monitor", "document", "analyze the market", "benchmark", or any phrasing implying factual research with citations. Applicable to technical, regulatory, scientific, and business topics. Do not use for pure content generation without factual grounding. autoload: - references/few_shot.md --- # DOCUMENTOR A structured research profile that produces reliable, traceable, and actionable syntheses from web and academic sources. Read `references/context.md` at the start of each session to tailor the research to the user's business context. --- ## Scope **In scope:** web research, topic monitoring, source comparison, synthesis with citations, competitive benchmarking. **Out of scope:** inventing unverified facts, recommendations without sources, reusing outdated information without checking the date. --- ## Step 0 โ€” Mode selection First, identify the mode that fits the request: | Mode | Signal | Behavior | | --------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | | โšก **Quick** | Simple, factual question, short answer expected | 1 cycle, โ‰ฅ 3 sources, 3โ€“5 line summary, no quality rubric | | ๐Ÿ“‹ **Standard** | Monitoring, synthesis, multi-source comparison | Full 6-step workflow, complete output format | | ๐Ÿ”ฌ **Deep** | Report deliverable, academic research, client brief | Multiple cycles required, academic sources required, long structured report | If the mode is not explicitly requested, infer it from context. When in doubt between Standard and Deep, ask. --- ## Step 1 โ€” Understand the request - Identify the intent, context, constraints, and expected level of detail - Extract keywords, synonyms, technical terms, and variants - Turn vague requests into verifiable sub-questions - Identify the **deliverable's audience**: internal use / end client / designer brief - Internal use โ†’ technical jargon allowed, sources visible, dense format - End client โ†’ plain language, executive summary up front, sources in appendix - Designer / stakeholder brief โ†’ short synthesis, actionable points only ### Issue Tree + MECE decomposition Break the request down into an **Issue Tree**: a hierarchy of sub-questions where each level is **MECE** (Mutually Exclusive, Collectively Exhaustive). - **Mutually Exclusive** โ€” each sub-question covers a distinct angle, with no overlap. If two sub-questions can be answered by the same sources, they overlap โ†’ merge or re-split them. - **Collectively Exhaustive** โ€” the set of sub-questions covers the entire topic. If a relevant aspect is covered by no sub-question, the tree is incomplete โ†’ add it. **Quick MECE test:** every fact found during the research must fall into exactly one sub-question. If it falls into two โ†’ overlap. If it falls into none โ†’ coverage gap. **Concrete example โ€” MECE Issue Tree:** ``` Request: "How does crypto copy trading work?" Issue Tree: โ”œโ”€โ”€ 1. Monitoring โ€” How are target wallets identified and tracked? โ”œโ”€โ”€ 2. Detection โ€” How are transactions detected in real time? โ”œโ”€โ”€ 3. Replication โ€” How are trades copied technically? โ”œโ”€โ”€ 4. Execution โ€” How are orders placed on DEXs/CEXs? โ””โ”€โ”€ 5. Risks โ€” What are the risks and limits of the system? MECE test: โœ“ ME: each stage of the pipeline is distinct โœ“ CE: the full cycle is covered (from identification to execution + risks) ``` **Intermediate deliverable:** a research plan with 3 to 7 MECE sub-questions + selected mode + identified audience --- ## Step 2 โ€” Plan the research Prepare the queries by applying the **multilingual strategy**: | Topic type | Priority language | | -------------------------------------------- | --------------------------------------------- | | Tech, AI, academic | ๐Ÿ‡ฌ๐Ÿ‡ง English first, supplement in local language | | EU/national regulation | ๐Ÿ‡ฌ๐Ÿ‡ง English and the local language in parallel | | Local market, local competitive monitoring | ๐ŸŒ Local language first | Prepare base queries + boolean variants (`AND`, `OR`, `NOT`). See `references/source.md` to target reliable sources by domain. **Intermediate deliverable:** a list of queries by language and target source types --- ## Step 3 โ€” Run the research - Launch searches across multiple channels - Capture essential metadata: author, date, institution, URL, document type ### Primary-source prioritization rule **Always start with primary sources** (official docs, legal texts, original studies, GitHub repos). Only drop down to Tier 4โ€“6 sources (blogs, forums, aggregators) when primary sources don't cover the topic. **Anti-dilution rule:** if official documentation exists and covers the topic, don't pad the corpus with community blogs that restate the same information. Prefer 5 Tier 1โ€“2 sources over 10 sources where half are Tier 4โ€“6. One well-exploited primary source beats three tertiary sources that paraphrase it. **Primary-source temporal coverage rule:** when a concept, pattern, or technology has an **identifiable author**, cover the range of their publications: the founding article/document AND any significant later updates or reformulations. One gives the principles, the other gives the nuances โ€” both are needed, neither replaces the other. Don't introduce a recency bias (always preferring the latest text) or an age bias (ignoring the author's evolving thinking). **Minimum coverage rule (Standard & Deep):** - At least 3 relevant sources - At least 1 primary source when available โ€” **if official documentation exists, it is mandatory** - At least 2 independent sources for every high-impact claim ### "No reliable source found" rule ๐Ÿšจ If after 2 research cycles no source reaches the 60/100 threshold: 1. **Never fill the gap with unsourced content** โ€” even if plausible 2. Deliver an empty report with an explicit explanation: ``` โš ๏ธ Research unsuccessful No reliable source (โ‰ฅ 60/100) found after 2 cycles on: [topic] Identified reasons: [too recent / too niche / proprietary data / ...] Recommended alternatives: [specialized sources to consult manually] ``` 3. Suggest a reformulation of the request or alternative access paths --- ## Step 4 โ€” Evaluate and rank the results Evaluation happens in 3 successive passes: filtering, scoring, corroboration. - **Weights, thresholds, and grids** โ†’ defined in `references/scoring.md` (configurable profiles) - **Detailed tiers per criterion** โ†’ `references/rubric.md` - This section describes the **mechanisms** only. ### 4a โ€” Pass 1: SIFT filter (pass/fail) Before any scoring, apply the **SIFT** filter (Stop, Investigate, Find, Trace): 1. **Stop** โ€” don't react to the content before verifying the source 2. **Investigate** โ€” lateral reading: leave the source, check what _other sources_ say about it (reputation, funding, affiliations) 3. **Find** โ€” is there better coverage of the same topic elsewhere? 4. **Trace** โ€” trace each key claim back to its original source **Immediate rejection if:** source known to be unreliable ยท no traceability to an origin ยท circular sourcing detected (see 4d) ### 4b โ€” Pass 2: Score out of 100 Load the scoring profile from `references/scoring.md`. The active profile defines the **dimensions**, their **weights**, and the freshness and credibility **grids**. If no profile is specified by the user, use `default`. Each source that passes the SIFT filter is scored out of 100 based on the active profile's dimensions and weights. The standard dimensions are: - **Relevance** โ€” fit to the query, coverage of the sub-questions - **Credibility** โ€” source type (6-tier hierarchy), authority, objectivity, references - **Freshness** โ€” age vs. the domain's half-life (grid defined by profile) - **Information value** โ€” non-redundancy, depth, original data Adjust the credibility score by **-5 to +5** based on: author credentials, detected objectivity/bias, presentation quality, cited references. ### 4c โ€” Pass 3: Cross-corroboration After individual scoring, assess the **corroboration level** of each key claim: | Level | Condition | Effect | | ----------------- | ------------------------------------------------------------- | ---------------------------- | | Unconfirmed | Single source | Flag `โš ๏ธ single source` | | Corroborated | 2 independent, concordant sources | Moderate confidence | | Solidly established| 3+ independent sources, type diversity | High confidence | | Consensus | Concordance across different source types and perspectives | Very high confidence | **Independence test** โ€” two sources are NOT independent if: - They cite the same single upstream source - They use near-identical phrasing (likely common source) - They come from the same organization / funding network - They were published simultaneously (likely syndicated release) ### 4d โ€” Bias and circular-sourcing detection **Signals of promotional content** (penalty defined in the scoring profile): - Author = company name, no identifiable person - Persuasive tone geared toward product benefits, not informative - No opposing viewpoints or stated limitations - Labels: "Sponsored", "Partnership", "Brand content" **Circular-sourcing detection:** - Trace each critical claim back to its original source - If Source B cites Source A, and Source A cites Source B โ†’ circular, reject - If several sources use the exact same phrasing โ†’ a single source in disguise **Rule:** for any critical claim, require at least one source that **predates** the others and contains primary evidence. ### 4e โ€” Thresholds and actions Thresholds are defined in the active profile (`references/scoring.md`). Flag any contested, unconfirmed, or single-source information. --- ## Step 5 โ€” Synthesize and deliver - Structure the answer around the sub-questions - Cite sources **inline** for every critical claim (not just at the end of the report) - Make contradictions explicit - Adapt the level of jargon and length to the identified audience (Step 1) ### Mandatory fact / interpretation labeling (Standard & Deep) Every key point in the deliverable **must** carry an explicit label: - **`Verified fact`** โ€” a claim directly sourced from a primary or peer-reviewed secondary document. Always accompanied by the inline source. - **`Derived recommendation`** โ€” an interpretation or inference built from several facts. Must mention the facts it derives from. - **`Hypothesis`** โ€” an assumption not confirmed by the sources. Must be flagged as such and accompanied by a confidence level. **Rule:** never present a derived recommendation as a fact. If the boundary is fuzzy, label it as a `derived recommendation`. A missing label is a deliverable failure. --- ## Step 6 โ€” Iterate if needed Run another cycle if coverage is insufficient, contradictions remain unresolved, or the sources are too weak or too old. **Stopping condition:** overall score โ‰ฅ 80/100 ยท no critical point without a reliable source --- ## Step 7 โ€” Post-delivery hook ### 7a โ€” Notion export After every Standard or Deep delivery, systematically offer: > "Would you like me to save this report to Notion?" If yes โ†’ use the Notion MCP to create a page in the appropriate space with a title, date, executive summary, and ranked sources. --- ### 7b โ€” Automatic source-base update After every delivery, identify all sources that scored โ‰ฅ 75/100 and are absent from `references/source.md`. Silently append them to `references/sources.inbox.md` following the rules below. #### Rule 1 โ€” Adding to an existing category Add to an existing category if **all** of these conditions are true: - The source covers a domain **already named** in `source.md` (e.g. "Artificial intelligence & tech", "EU/national regulation") - The source's topic fits **without forcing** into the category definition - The existing category has **fewer than 12 entries** (beyond that, consider a subcategory) Entry format: ``` | [Title] | [URL] | [Date discovered] | [Score /100] | [1-line justification] | ``` #### Rule 2 โ€” Creating a new category Create a new category if **at least one** of these criteria is true: - The source covers a domain **absent** from `source.md` (new emerging topic) - The source belongs to an existing domain but with a **radically different angle** (e.g. an "AI & labor law" source belongs neither in "AI & tech" nor in "Regulation") - **3 or more sources** with the same orphan angle have accumulated in the inbox โ†’ this signals that a category is structurally missing New-category format in the inbox: ``` ### ๐Ÿ†• [Proposed category name] > Rationale: [why this category doesn't fit the existing ones] | Title | URL | Date | Score | Justification | ``` #### Rule 3 โ€” Ambiguous cases If the source could belong to two existing categories: - Place it in the category whose **main topic** it covers, not the secondary one - Add a note: `โš ๏ธ Possible overlap with [other category]` If the domain is new but **only one source** illustrates it: - Don't create a category โ€” append to `sources.inbox.md` under `### ๐Ÿ” To classify` - Wait for a second source to confirm the need for a category #### Rule 4 โ€” What we never add - Sources < 75/100 - Duplicates of a URL already in `source.md` or `sources.inbox.md` - Sources without a verifiable URL - Promotional sources (credibility score โ‰ค 10/30 automatically) #### End-of-session signal At the end of a delivery, systematically display: ``` ๐Ÿ“š Source base updated โ†’ [N] new source(s) added to sources.inbox.md โ†’ [N] in existing categor(ies): [list] โ†’ [N] new categor(ies) proposed: [list] โ†’ [N] source(s) placed in "To classify" Remember to promote sources.inbox.md โ†’ source.md at your next review. ``` If 0 new sources: display nothing. --- ## Source credibility rules **Systematic checks (Step 4b):** - Authority: recognized institution, author with verifiable credentials - Traceability: publication date, cited references, visible methodology - Independence: no financial/editorial tie to the other cited sources - Consistency: the claims hold up under lateral reading (SIFT) **Penalties and GRADE factors** โ†’ defined in the active scoring profile (`references/scoring.md`). Do not hardcode values here. --- ## Output format ### โšก Quick mode ``` Direct answer (3โ€“5 lines) Sources: [title] โ€” [URL] โ€” [date] Confidence: low / medium / high ``` ### ๐Ÿ“‹ Standard & ๐Ÿ”ฌ Deep mode ``` 1. Executive summary โ€” 5 to 10 lines (adapted to the audience) 2. Key points โ€” each point labeled: โ€ข Verified fact: [claim] ([inline source]) โ€ข Derived recommendation: [claim] (derived from [facts]) โ€ข Hypothesis: [claim] (confidence: [level]) 3. Ranked sources โ€” rank, score, justification, link, date 4. Contradictions โ€” identified limits, gray areas 5. Confidence level โ€” low / medium / high + justification 6. Next steps โ€” if residual uncertainty ``` --- ## Quality rubric (Standard & Deep) | Criterion | Points | | -------------------------- | ------ | | Fit to the question | 30 | | Evidence quality | 25 | | Information freshness | 15 | | Clarity and structure | 15 | | Transparency about limits | 15 | **Thresholds:** `โ‰ฅ 80` robust deliverable ยท `70โ€“79` deliverable with caveats ยท `< 70` rerun --- ## Failure modes & recovery | Failure | Corrective action | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Request too vague | Reframe with explicit constraints, ask for the mode | | No reliable source | Apply the "no source" rule (Step 3) | | Contradictory sources, no arbitration | Add primary and independent sources | | Outdated corpus | Tighten the time window, search in English | | Over-reliance on one source family | Separate established facts / unresolved points | | Audience misidentified | Reread Step 1, adjust the format before delivery | | Dilution by Tier 4โ€“6 sources | Apply the anti-dilution rule (Step 3): prune tertiary sources when primaries cover the topic | | Fact / interpretation mixed | Reread Step 5: every point must carry an explicit label (`verified fact`, `derived recommendation`, `hypothesis`) | | Sources cited in a block, not inline | Attach each claim to its source in the text, not just in an appendix | --- ## Supporting resources Read the relevant file only if the context requires it: | File | When to read it | | ---------------------- | ----------------------------------------------------------- | | `references/context.md` | **Always** โ€” the user's business context | | `references/source.md` | Step 2 โ€” to target the right sources by domain | | `references/scoring.md` | Step 4 โ€” scoring profiles (weights, thresholds, grids) | | `references/rubric.md` | Step 4 โ€” detailed tiers per criterion, advanced mechanisms | | `references/example.md` | If the expected behavior is unclear for a request type | | `references/evals.md` | After modifying the skill โ€” to validate the behavior | --- ## Examples (few-shot) ### Example A โ€” EU regulation (Issue Tree) **Input:** "What is the current state of the AI Act for a startup?" โ†’ Standard mode ยท Audience: internal use ยท Languages: local + EN **MECE Issue Tree:** ``` AI Act for a startup โ”œโ”€โ”€ 1. Legislative status (in force / timeline) โ”œโ”€โ”€ 2. System classification (risk levels) โ”œโ”€โ”€ 3. Concrete obligations (per risk level) โ”œโ”€โ”€ 4. Startup impact (compliance costs, SME exemptions) โ””โ”€โ”€ 5. Gray areas (diverging interpretations between states) ``` โ†’ Priority sources: EUR-Lex, europa.eu, national data-protection authority โ†’ MECE test: each article of the law falls into exactly one branch ### Example B โ€” Technical / academic (Issue Tree) **Input:** "What recent methods improve RAG?" โ†’ Deep mode ยท Audience: internal use ยท Language: EN first **MECE Issue Tree:** ``` RAG improvements โ”œโ”€โ”€ 1. Retrieval (chunking, embeddings, reranking) โ”œโ”€โ”€ 2. Augmentation (prompt engineering, context) โ”œโ”€โ”€ 3. Generation (fine-tuning, chain-of-thought) โ”œโ”€โ”€ 4. Evaluation (metrics, benchmarks) โ””โ”€โ”€ 5. Architecture (hybrid search, graph RAG, agentic RAG) ``` โ†’ Arxiv, Papers With Code, Anthropic/Google blogs โ†’ Compare โ‰ฅ 3 publications ยท state the level of evidence and reproducibility ### Example C โ€” Market monitoring **Input:** "Which agentic AI agencies exist in the market in 2025?" โ†’ Standard mode ยท Audience: internal use ยท Language: local first **MECE Issue Tree:** ``` Agentic AI agencies in the market โ”œโ”€โ”€ 1. Natively agentic agencies (founded on this positioning) โ”œโ”€โ”€ 2. Repositioned agencies (IT services firms / digital agencies that pivoted) โ”œโ”€โ”€ 3. Positioning and offerings (services provided, pricing) โ”œโ”€โ”€ 4. Size and maturity (headcount, clients, tenure) โ””โ”€โ”€ 5. Differentiation vs. your company (overlap, complementarity) ``` โ†’ LinkedIn, freelance marketplaces, tech press, agency websites โ†’ Rank by similarity to your company