skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/research/skills/research-plan/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: research-plan
+description: Turn a vague research question into a research plan — the decision the research serves, the precise question and sub-questions, what finding would change the decision, a method per sub-question (desk research, interviews, data pull, experiment), source types with inclusion and exclusion criteria, ready-to-run search strings, a stopping rule for when you have enough, and the deliverable. Starts by asking what decision the research is for. Use when the user says "I need to research X", "help me scope this research", "how should I investigate…", "what should I look into before deciding…", or wants a research or discovery plan.
+---
+
+# research-plan
+
+You turn "can you look into X?" into a plan that someone can run and finish. Research without
+a decision attached never ends, so the plan starts from the decision and works back: what
+would have to be true to choose A over B, which sub-questions test that, how to answer each
+one, and when to stop. The output is a one-to-two page plan, not the research itself.
+
+The plan feeds two siblings: `source-synthesis` turns the sources you collect into cited
+findings, and `hypothesis-comparison` ranks rival explanations when the question is "why did
+this happen?". If interviews are one of the methods, `requirements-interview` writes the
+question scripts for stakeholder interviews.
+
+## How to respond
+
+1. **Ask about the decision first, in one message.** Ask: *"What decision will this research
+   inform, who makes it, and by when?"* Add one more question only if needed: what the user
+   already believes the answer is. That's at most two questions. Research without a decision
+   is the main failure this skill prevents, so don't skip this step even if the topic is
+   clear. ✅ *"Whether to move support to a four-day week from January; the COO decides on
+   1 Nov."* ❌ *"Understand four-day weeks."*
+
+2. **Write the precise question.** One sentence that names the population, the thing being
+   tested, the comparison and the timeframe. ✅ *"For a 14-person B2B support team, does a
+   four-day week keep first-response time within 10% of today over six months?"* ❌ *"Do
+   four-day weeks work?"* If the user's question can't be answered in the time they have,
+   narrow it and say what you cut.
+
+3. **Break it into three to six sub-questions.** Each one must be answerable on its own and
+   matter to the decision. Drop any sub-question whose answer wouldn't change what the user
+   does, however interesting it is.
+
+4. **Say what would change the decision.** For each sub-question, write the finding that would
+   push the decision one way or the other, with a threshold where one makes sense: *"If
+   response times rise more than 10% in comparable pilots, don't move without a staggered
+   rota."* Write these before any research starts, so the findings can't be read to fit.
+   Note the user's current belief and what evidence would overturn it.
+
+5. **Pick a method per sub-question.** Choose the cheapest method that can answer it, from
+   desk research, interviews, a data pull, a survey, or an experiment (the guide is in
+   [`reference.md`](reference.md)). For each, give the sample or scope, who does it, and
+   the time it takes. Prefer existing data over new data, and a data pull over a survey.
+
+6. **Define the sources.** For desk research, list the source types to use in order of
+   weight (primary studies, official statistics, industry surveys, practitioner write-ups,
+   news) and write **inclusion and exclusion criteria**: date range, geography, population,
+   language, study type, and minimum method standard. ✅ *"Include: pilots or studies from
+   2019 on, in knowledge-work or support roles, with a before-and-after measure. Exclude:
+   opinion pieces, vendor marketing, manufacturing shifts."*
+
+7. **Write the search strings.** Give strings the user can paste, with synonyms grouped in
+   `OR` and concepts joined with `AND`, plus where to run each (Google Scholar, a named
+   database, company filings, internal wiki). Note the date filter. Search syntax differs by
+   engine; the notes are in [`reference.md`](reference.md).
+
+8. **Set the stopping rule.** Say when the research is done, before it starts. Combine a
+   **sufficiency** test (each sub-question answered to the confidence the decision needs, or
+   new sources stop changing the answer: "three sources in a row add nothing new") with a
+   **budget** cap (hours or a date). When the cap comes first, the deliverable says which
+   sub-questions are still open.
+
+9. **Name the deliverable.** State the format, the audience, and the date: for example, a
+   two-page synthesis with cited findings and a recommendation, made with `source-synthesis`.
+   List the risks to the plan (no access to data, biased sources, too few interviewees) with
+   a fallback for each.
+
+10. **Write it up with [`templates/research-plan.md`](templates/research-plan.md).** Keep it
+    to two pages. A plan longer than that tends to get made instead of the research.
+
+**Non-interactive runs** (subagent, CI, headless): if the decision can't be inferred from the
+input, emit `BLOCKED: need the decision this research informs, who makes it, and by when`.
+If it can be inferred, state it as `[assumption] Decision: …` at the top. Missing deadlines and
+budgets become tagged assumptions (default: two weeks, 15 hours).
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — choosing a method, inclusion and exclusion criteria, search-string syntax by engine, stopping rules, and planning failures
+- [`templates/research-plan.md`](templates/research-plan.md) — the plan skeleton
+- [`examples/four-day-week-plan.md`](examples/four-day-week-plan.md) — worked example: a vague request becomes a decision-led plan
+
+## Quality bar
+
+- **The plan names the decision, who makes it, and the date.** Every sub-question traces back to it.
+- **The question is precise:** population, intervention or topic, comparison, timeframe.
+- **Each sub-question has a "would change the decision" finding,** written before research starts, with a threshold where one makes sense.
+- **Each sub-question has a method, a scope, an owner and a time,** and the method is the cheapest one that can answer it.
+- **Inclusion and exclusion criteria are explicit** for desk research: dates, geography, population, source type.
+- **Search strings are ready to paste,** with synonyms and where to run them.
+- **There is a stopping rule** with both a sufficiency test and a budget cap.
+- **Nothing in the plan states findings.** It doesn't present a guess at the answer as known.
+
+## When to use this skill
+
+- ✅ "I need to research X before we decide Y"
+- ✅ Scoping desk research, a literature review or a discovery sprint
+- ✅ A question that keeps growing and needs a boundary and an end date
+- ✅ Choosing between interviews, data, surveys and experiments for a question
+
+## When NOT to use this skill
+
+- ❌ The sources are already collected and need summarising — `source-synthesis`
+- ❌ Ranking rival explanations for something that already happened — `hypothesis-comparison`
+- ❌ Writing the interview scripts for stakeholders — `requirements-interview`
+- ❌ A strategy framework such as SWOT or Five Forces on a market — `strategy-analysis`
+- ❌ Comparing named technologies or vendors — `tech-comparison-matrix`
+- ❌ Turning a messy thread into a brief for another skill — `brief-intake`
+
+## Anti-patterns to avoid
+
+- ❌ **Research with no decision.** "Learn about four-day weeks" has no end and no use.
+- ❌ **A dozen sub-questions.** Six is the most a person can work through; cut the ones that wouldn't change the decision.
+- ❌ **Writing the thresholds after the findings.** Then any result can be read as support.
+- ❌ **A survey by default.** Check whether the answer already sits in data you have.
+- ❌ **"Search Google for four-day week".** Give the string, the synonyms, the engine and the date filter.
+- ❌ **No stopping rule.** The research ends when the budget runs out, with nothing written.
+- ❌ **Only sources that agree with the user's belief.** Include a search for the opposite.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/research/skills/research-plan/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "I need to research whether we should move to usage-based pricing before the board meeting. Help me scope it.",
+    "should_trigger": true
+  },
+  {
+    "query": "How should I investigate why enterprise customers take so long to onboard? Give me a research plan.",
+    "should_trigger": true
+  },
+  {
+    "query": "Plan the desk research for a literature review on hybrid work, with search strings and inclusion criteria",
+    "should_trigger": true
+  },
+  {
+    "query": "My research on this keeps growing. Help me define the sub-questions and when to stop.",
+    "should_trigger": true
+  },
+  {
+    "query": "Here are five reports I've collected; synthesise them with citations",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the interview questions for the sponsor and the ops lead before we build the feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Do a SWOT on our position against Contoso",
+    "should_trigger": false
+  },
+  {
+    "query": "Compare Postgres and DynamoDB for this workload",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/research/skills/research-plan/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "research-plan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to research whether Northwind should build a self-serve onboarding flow instead of our current sales-led onboarding for small customers. The VP of Growth decides in Q1 planning on 15 January. We have product analytics in Amplitude and about 200 small customers. I've got maybe 25 hours.",
+      "assertions": [
+        "Opens with the decision, who makes it (VP of Growth) and the date (15 January), taken from the prompt",
+        "States one precise question naming the population, the change, the comparison and a timeframe",
+        "Breaks it into three to six sub-questions, each tied to the decision",
+        "Gives each sub-question a finding that would change the decision, with a threshold where one makes sense",
+        "Picks a method per sub-question with scope, owner and time, and prefers the existing Amplitude data over a new survey",
+        "Writes inclusion and exclusion criteria and paste-ready search strings, including one for the opposite view",
+        "Sets a stopping rule with both a sufficiency test and a budget cap within the 25 hours",
+        "Does not state findings or invent facts about Northwind not in the prompt; inferred items are tagged [assumption]"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Research AI coding assistants for me.",
+      "assertions": [
+        "Asks what decision the research will inform, who makes it and by when, before writing a plan",
+        "Asks no more than two questions",
+        "Does not produce a full plan around an invented decision"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/research/skills/research-plan/examples/four-day-week-plan.md

@@ -0,0 +1,97 @@
+# Worked example — "can you look into four-day weeks?"
+
+## Input given to the skill
+
+> Can you research four-day weeks for me? People keep bringing it up.
+
+## The skill's one question
+
+> Before I plan this: **what decision will the research inform, who makes it, and by when?**
+> And what do you think the answer is right now?
+
+## User's reply
+
+> Our COO, Dana, has to decide by 1 November whether Acme's support team (14 people, B2B
+> SaaS) goes to a four-day week from January. I think it'd be great for morale but I'm worried
+> about response times. I've got about 20 hours over the next three weeks, and I can get
+> ticket data from Zendesk.
+
+---
+
+## Output
+
+# Research plan: four-day week for Acme support
+
+_Prepared 2026-10-01 · Owner: the user · Due: 24 Oct 2026 (a week before the decision)_
+
+## Decision
+
+**Decision:** whether Acme's support team moves to a four-day week from January 2027.
+**Decided by:** Dana (COO) · **By:** 1 Nov 2026
+**Current belief:** good for morale, risky for response times. Overturned if comparable teams
+kept response times within 10% and a rota is workable for 14 people.
+
+## Question
+
+For a 14-person B2B SaaS support team, does a four-day week keep first-response time within
+10% of today and hold resolution volume, over six months, compared with the current five-day
+week?
+
+Out of scope: pay and contract changes (HR's question, after the decision), other teams,
+and four-day weeks with longer days.
+
+## Sub-questions
+
+| # | Sub-question | Would change the decision if… | Method | Scope | Owner | Time |
+|---|---|---|---|---|---|---|
+| Q1 | What happened to response times and output in comparable pilots? | Response times rose more than 10% in most support-role pilots | Desk research | 15–25 sources screened, 5–10 kept | User | 8 h |
+| Q2 | How does our ticket load spread across the week? | Friday and Monday together carry more than 45% of tickets, making a shared day off unworkable | Data pull | Zendesk, last 12 months, by weekday and hour | User + support ops | 3 h |
+| Q3 | Can 14 people cover five days with staggered days off? | Fewer than 3 agents on any day at the current headcount | Rota model from Q2 data | One spreadsheet model | User | 3 h |
+| Q4 | What does the team expect, and what worries them? | A majority of the team would prefer not to change | Short interviews | 5 agents and the team lead | User | 4 h |
+| Q5 | Did any comparable team reverse its four-day week, and why? | Reversals cite customer coverage in support roles | Desk research (opposite-view search) | Included in Q1's budget | User | in Q1 |
+
+## Sources (desk research)
+
+**Source types, by weight:** pilot reports with before-and-after data; peer-reviewed studies;
+surveys with stated sample and method; practitioner write-ups from support teams; news only
+to find the underlying report.
+
+**Include:** 2019 onwards; knowledge-work, support or customer-service roles; a measure of
+output or response time before and after; UK, EU or North America.
+**Exclude:** opinion pieces and vendor marketing (no data); manufacturing and shift work
+(different coverage model); "four-day weeks" that keep 40 hours over four days (a different
+intervention).
+
+## Search strings
+
+| For | String | Where | Filter |
+|---|---|---|---|
+| Q1 | `("four-day week" OR "4-day week" OR "reduced working week") AND (pilot OR trial) AND (productivity OR "response time" OR output)` | Google Scholar | 2019 onwards |
+| Q1 | `("four-day week" OR "4-day week") AND ("customer support" OR "customer service" OR helpdesk)` | Google | past 5 years |
+| Q5 | `("four-day week" OR "4-day week") AND (reversed OR abandoned OR "went back" OR ended)` | Google | past 5 years |
+
+## Stopping rule
+
+- **Enough when:** Q1 has at least three support-role sources with response-time or output
+  data, and three more sources in a row add nothing new; Q2 to Q4 are answered.
+- **Budget cap:** 20 hours or 24 Oct, whichever comes first. At the cap, deliver with the open
+  sub-questions listed.
+
+## Deliverable
+
+A two-page synthesis for Dana by 24 Oct: cited findings for Q1 and Q5 (made with
+`source-synthesis`), the Q2 weekday chart, the Q3 rota, the Q4 interview themes, and a
+recommendation with the threshold each finding was judged against.
+
+## Risks to the plan
+
+| Risk | Fallback |
+|---|---|
+| Few published pilots cover support roles | Widen to all customer-facing roles and rate the evidence limited |
+| Zendesk export lacks timestamps by hour | Use daily counts; the Q3 rota then works at day level |
+| Interviewees tell the user what they think the user wants | Ask what would make it fail, and include the team lead's view separately |
+
+## Assumptions to confirm
+
+- [assumption] "Four-day week" means 32 hours at the same pay, not 40 hours over four days.
+- [assumption] Current headcount stays at 14 through the pilot.

skilldrop_cli/data/packs/research/skills/research-plan/manifest.json

@@ -0,0 +1,47 @@
+{
+  "name": "research-plan",
+  "version": "0.1.1",
+  "description": "Turn a vague research question into a research plan — the decision the research serves, the precise question and sub-questions, what finding would change the decision, a method per sub-question (desk research, interviews, data pull, experiment), source types with inclusion and exclusion criteria, ready-to-run search strings, a stopping rule for when you have enough, and the deliverable. Starts by asking what decision the research is for. Use when the user says \"I need to research X\", \"help me scope this research\", \"how should I investigate…\", \"what should I look into before deciding…\", or wants a research or discovery plan.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brief-intake",
+    "hypothesis-comparison",
+    "requirements-interview",
+    "source-synthesis",
+    "strategy-analysis",
+    "tech-comparison-matrix"
+  ],
+  "handoff": [
+    {
+      "to": "source-synthesis",
+      "when": "the sources in the plan have been collected",
+      "purpose": "Turn them into cited findings, with agreement, strength and gaps, judged against the plan's thresholds.",
+      "fallback": "If source-synthesis is absent, write one finding per sub-question with a source and page for every claim, and list what no source answered."
+    },
+    {
+      "to": "requirements-interview",
+      "when": "interviews are a method in the plan and the interviewees are stakeholders",
+      "purpose": "Write the per-stakeholder question scripts.",
+      "fallback": "If requirements-interview is absent, write five open questions per group inline, each tied to the sub-question it answers, with one question that invites disagreement."
+    }
+  ],
+  "tags": [
+    "research",
+    "planning",
+    "discovery",
+    "method",
+    "search"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Structured planning against a fixed shape (decision, sub-questions, methods, criteria, stopping rule); needs judgment to cut scope but no adversarial reasoning."
+  }
+}

skilldrop_cli/data/packs/research/skills/research-plan/reference.md

@@ -0,0 +1,88 @@
+# research-plan — reference
+
+## Choosing a method
+
+Pick the cheapest method that can answer the sub-question to the confidence the decision needs.
+
+| Method | Use when the sub-question is | Typical scope | Watch out for |
+|---|---|---|---|
+| **Data pull** | "How much / how often / what changed" and you already have the data | A query over existing records, one to three days | Definitions that changed over time; data that measures a proxy |
+| **Desk research** | "What do others know": published studies, statistics, competitor material | 10–30 sources screened, 5–12 kept | Publication bias, vendor marketing, old data |
+| **Interviews** | "Why / how / what's it like" from people with direct experience | 5–12 people per group | Leading questions, only talking to fans, small samples read as statistics |
+| **Survey** | "How common is this view" across a group too large to interview | Enough responses for the split you need | Low response rates, self-report bias, questions that suggest the answer |
+| **Experiment or pilot** | "Does X cause Y here", and the decision is costly to reverse | A test group and a comparison group, a fixed period | Too short to show the effect; no baseline |
+
+Rules of thumb:
+
+- Existing data before new data. A data pull before a survey.
+- Interviews explain; they don't measure. Never report "7 of 10 interviewees" as a percentage
+  of a population.
+- Run an experiment only when the decision justifies the time, and say up front what result
+  counts as success.
+
+## Inclusion and exclusion criteria
+
+Write them before searching so the source list can't drift towards the answer you want.
+
+| Dimension | Example inclusion | Example exclusion |
+|---|---|---|
+| Date | Published 2019 onwards | Before 2019, unless it's the original study others cite |
+| Geography | UK, EU, North America | Regions with different labour law, if that matters to the decision |
+| Population | Knowledge workers, support or service roles | Manufacturing, shift work |
+| Source type | Primary studies, pilot reports, official statistics, surveys with stated methods | Opinion pieces, vendor marketing, press releases with no data |
+| Method | Before-and-after with a baseline, or a comparison group | Self-report only, with no baseline |
+| Language | English | Others, unless translation is available |
+
+Record why each excluded source was excluded, in one word, so the user can see the screen
+was fair.
+
+## Search strings
+
+Group synonyms with `OR` inside brackets, join concepts with `AND`, and quote phrases.
+
+```
+("four-day week" OR "4-day week" OR "compressed workweek" OR "reduced hours")
+AND (productivity OR output OR "response time")
+AND (pilot OR trial OR study)
+```
+
+Engine notes. Check the engine's own help page before relying on an operator; these are the
+common, documented ones:
+
+- **Google and Google Scholar:** quotes for phrases, `OR` in capitals, `-` to exclude a word,
+  `site:` to restrict to a domain (Google web search). Scholar has a date-range filter in
+  the left sidebar.
+- **Academic databases** (for example, library databases a university or company subscribes
+  to): most support `AND`, `OR`, `NOT`, brackets and quotes, and many support `*` as a
+  truncation wildcard. Field tags differ by database.
+- **Internal wikis and drives:** usually keyword only. Run each synonym as its own search.
+
+Always add one search for the opposite of what the user expects:
+
+```
+("four-day week" OR "compressed workweek") AND (failed OR abandoned OR reversed OR "customer complaints")
+```
+
+## Stopping rules
+
+Set both kinds. Stop at whichever comes first.
+
+- **Sufficiency (saturation):** each sub-question has an answer at the confidence the decision
+  needs, or the last three sources or interviews added nothing new to it.
+- **Budget:** a cap in hours or a date. When the cap comes first, deliver what you have and
+  list the open sub-questions with what it would take to close each.
+
+Confidence the decision needs depends on how costly and reversible it is. A reversible,
+cheap decision needs a direction, not proof. A costly, one-way decision needs the strongest
+evidence available, and may justify a pilot.
+
+## Planning failures
+
+- **The question changes mid-way** and nobody notices. Re-read the plan's question at each
+  check-in; if it changed, change the plan on purpose.
+- **Sub-questions nobody needs.** Test each one: "if the answer is X, what do we do
+  differently?" No change, cut it.
+- **Thresholds written after the findings.** Write them first.
+- **Access assumed.** Confirm early that the data, people and paywalled sources are reachable.
+- **One method for everything.** Usually the right plan mixes a data pull, some desk research
+  and a few interviews.

skilldrop_cli/data/packs/research/skills/research-plan/templates/research-plan.md

@@ -0,0 +1,54 @@
+# Research plan: {topic, in a few words}
+
+_Prepared {YYYY-MM-DD} · Owner: {who runs the research} · Due: {date}_
+
+## Decision
+
+**Decision:** {what will be decided, in one sentence}
+**Decided by:** {person or group} · **By:** {date}
+**Current belief:** {what the decider thinks now, and what would overturn it}
+
+## Question
+
+{One sentence: population, intervention or topic, comparison, timeframe.}
+
+Out of scope: {what was cut to make the question answerable in time}
+
+## Sub-questions
+
+| # | Sub-question | Would change the decision if… | Method | Scope | Owner | Time |
+|---|---|---|---|---|---|---|
+| Q1 | {question} | {finding, with a threshold} | {data pull / desk / interviews / survey / experiment} | {sample or sources} | {who} | {hours or days} |
+
+## Sources (desk research)
+
+**Source types, by weight:** {primary studies, pilot reports, official statistics, surveys with stated methods, practitioner write-ups, news}
+
+**Include:** {date range, geography, population, source type, method standard}
+**Exclude:** {and why}
+
+## Search strings
+
+| For | String | Where | Filter |
+|---|---|---|---|
+| Q1 | `("…" OR "…") AND (… OR …)` | {engine or database} | {date range} |
+| Opposite view | `("…") AND (failed OR abandoned OR reversed)` | … | … |
+
+## Stopping rule
+
+- **Enough when:** {each sub-question answered to the confidence needed, or three sources in a row add nothing new}
+- **Budget cap:** {hours} hours or {date}, whichever comes first. At the cap, deliver with the open sub-questions listed.
+
+## Deliverable
+
+{Format, length, audience, date. For example: a two-page cited synthesis with a recommendation, for the COO, by {date}.}
+
+## Risks to the plan
+
+| Risk | Fallback |
+|---|---|
+| {no access to data, biased sources, too few interviewees} | {what to do instead} |
+
+## Assumptions to confirm
+
+- [assumption] {anything inferred rather than given}

skilldrop_cli/data/packs/research/skills/source-synthesis/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: source-synthesis
+description: Synthesise a set of supplied sources — papers, articles, reports, interview transcripts — into findings where every claim is cited to a source and a location ([S1:p4]), agreement and disagreement across sources are explicit, each finding carries an evidence-strength rating with the criteria used, and the gaps and what the sources do not say are listed. Never adds outside facts unless tagged as such, and ships a citation checker. Use when the user hands over several sources and asks to "synthesise these", "what do these papers say", "literature review", "pull the findings together", or "where do the sources agree and disagree".
+---
+
+# source-synthesis
+
+You turn a pile of sources the user supplied into findings they can rely on and check. Every
+claim points to a source and a place in it, so a reader can verify it in under a minute.
+Where sources agree, you say how many and which; where they disagree, you show both sides and
+why they might differ. You add nothing from your own knowledge unless it is tagged
+`[outside]`. The synthesis is only as good as its sources, so each finding says how strong its
+evidence is and on what criteria.
+
+What to research and where to look comes first, from `research-plan`. If the findings point to
+several rival explanations, rank them with `hypothesis-comparison`. To turn messy material into
+a brief for another skill rather than findings, use `brief-intake`.
+
+## How to respond
+
+1. **Ask once for what's missing.** You need the **sources** themselves (text, files or
+   excerpts, not titles) and the **question** the synthesis answers. If the user has a
+   research plan, take the question and sub-questions from it. Ask for both in one message.
+   If the user sends only titles or links you can't open, ask for the text. Don't summarise a
+   paper from memory.
+
+2. **Register the sources.** Give each one an id (`S1`, `S2`, …) and one line: author or owner,
+   title, date, type (peer-reviewed study, survey, internal report, news article, interview,
+   opinion piece), and for studies the method and sample size if the source states them. Note
+   how location works in each: page numbers, section numbers, or timestamps for transcripts.
+   Mark sources that aren't independent (two articles reporting the same survey count as one
+   line of evidence).
+
+3. **Extract claims before you synthesise.** For each source, list the claims that bear on the
+   question, each with its location, in the source's own terms. Keep the source's hedges:
+   "associated with" stays "associated with", not "causes". Quote the key sentence when the
+   wording matters.
+
+4. **Group claims into findings, one per sub-question or theme.** For each finding:
+   - **State it in one sentence,** worded no stronger than its weakest supporting source.
+   - **Cite every source that supports it,** with locations: `[S1:p4; S3:§2.1]`.
+   - **Show agreement and disagreement:** "S1, S3 and S4 agree; S2 disagrees", and give the
+     likely reason for the disagreement when the sources show one (different population,
+     period, definition or method). Don't average conflicting results into a middle answer.
+   - **Rate the evidence strength** (strong / moderate / limited / conflicting) and say which
+     criteria drove it: independent sources, source type, method, sample size, recency,
+     directness. Criteria are in [`reference.md`](reference.md).
+
+5. **List the gaps and what the sources don't say.** Sub-questions no source answers;
+   populations, periods or regions no source covers; claims everyone repeats but nobody tests;
+   and the question the user is likely to ask next that these sources can't answer. Write
+   these as statements: ✅ *"None of the sources measures effects beyond 12 months."*
+
+6. **Tag anything from outside.** If context the sources don't give is genuinely needed (a
+   definition, a well-known date), add it with `[outside]` so the reader knows to check it.
+   Keep it rare. Never use `[outside]` to fill a gap in the findings; list the gap instead.
+
+7. **Write it up with [`templates/synthesis.md`](templates/synthesis.md):** the question, the
+   source register, the bottom line in three sentences or fewer, findings with citations and
+   strength, the agreement and disagreement table, gaps, what the sources do not say, and the
+   `[outside]` list.
+
+8. **Check every citation.** Save the draft and run:
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/citations.py" synthesis.md -o citation-check.md
+   # Other IDEs (from the skill folder)
+   python3 scripts/citations.py synthesis.md -o citation-check.md
+   ```
+
+   It reads the `## Sources` section of the draft (or a separate file with `--sources`), and
+   reports citations that don't resolve, malformed citations, paragraphs and table rows with no
+   citation, citations with no location, sources never cited, and every `[outside]` claim. Fix
+   every error, and either fix or explain each warning. A source never cited is a question:
+   did it say nothing relevant, or did you miss it? Say which in the source register.
+
+**Non-interactive runs** (subagent, CI, headless): with no source text, emit
+`BLOCKED: need the sources' text, not titles or links`. A missing question becomes
+`[assumption] The question is: …`, inferred from the sources and stated at the top.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — citation format, evidence-strength criteria, how to handle disagreement, independence, and common distortions
+- [`templates/synthesis.md`](templates/synthesis.md) — the synthesis skeleton
+- [`scripts/citations.py`](scripts/citations.py) — checks that every citation resolves and every claim is cited (stdlib only)
+- [`examples/four-day-week.md`](examples/four-day-week.md) — worked example: four sources on a four-day-week pilot, the synthesis, and the checker's real output on a first draft and the fixed draft
+
+## Quality bar
+
+- **Every claim is cited to a source and a location.** The checker reports no errors; any warning left is explained.
+- **Nothing comes from outside the sources** unless it is tagged `[outside]`, and gaps are never filled from memory.
+- **Agreement and disagreement are explicit,** with the sources named on each side and a likely reason for the split where the sources show one.
+- **Each finding has a strength rating and the criteria behind it.** A finding from one survey never reads like one from three independent studies.
+- **Findings are no stronger than their sources.** Hedges survive; correlation stays correlation.
+- **Gaps and what the sources do not say are listed** as specific statements.
+- **Sources that aren't independent are counted once.**
+
+## When to use this skill
+
+- ✅ "Synthesise these six papers / reports / articles on X"
+- ✅ Turning a set of interview transcripts into cited themes
+- ✅ A literature review or evidence summary for a decision
+- ✅ Checking where a set of analyst reports agree and where they don't
+
+## When NOT to use this skill
+
+- ❌ Deciding what to research, which sources to look for and when to stop — `research-plan`
+- ❌ Ranking rival explanations for something that happened — `hypothesis-comparison`
+- ❌ Turning one thread or transcript into a brief for another skill — `brief-intake`
+- ❌ Pulling decisions and action items out of meeting notes — `decision-log`
+- ❌ A market or competitor analysis with a framework — `strategy-analysis`
+- ❌ Reviewing a document someone else wrote — `doc-critique`
+
+## Anti-patterns to avoid
+
+- ❌ **Source-by-source summaries.** "S1 says…, S2 says…" is an annotated list, not a synthesis. Organise by finding.
+- ❌ **A citation with no location.** `[S2]` on a 60-page report can't be checked.
+- ❌ **Smoothing over conflict.** "Results were mixed" hides which sources disagree and why.
+- ❌ **Promoting hedges.** "May be associated with" becomes "drives" by the second paragraph.
+- ❌ **Counting echoes.** Three news stories about one study are one source.
+- ❌ **Filling gaps from memory.** A plausible fact with no source is the error this skill exists to prevent.
+- ❌ **Citing a title you haven't read.** If you only have the abstract, say so in the register and rate accordingly.

skilldrop_cli/data/packs/research/skills/source-synthesis/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Here are six papers on remote work and productivity. Synthesise what they say, with citations to page numbers.",
+    "should_trigger": true
+  },
+  {
+    "query": "Pull together the findings from these four analyst reports and show where they agree and disagree",
+    "should_trigger": true
+  },
+  {
+    "query": "I've got eight customer interview transcripts. Give me the cited themes and how strong the evidence is for each.",
+    "should_trigger": true
+  },
+  {
+    "query": "Write a short literature review from these sources, and don't add anything that isn't in them",
+    "should_trigger": true
+  },
+  {
+    "query": "Help me plan the research before I start looking for sources on four-day weeks",
+    "should_trigger": false
+  },
+  {
+    "query": "Turn this Slack thread into a brief I can hand to the ADR generator",
+    "should_trigger": false
+  },
+  {
+    "query": "Pull the decisions and action items out of these meeting notes",
+    "should_trigger": false
+  },
+  {
+    "query": "Here are the facts we have; which of these three explanations for the churn spike holds up best?",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/research/skills/source-synthesis/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "source-synthesis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Synthesise these three sources on whether Northwind should offer annual billing discounts. S1: Contoso pricing benchmark 2026 (40 pp.): p12 'median annual discount among 300 SaaS firms is 17%'; p15 'annual plans churn 40% less, though firms self-select annual buyers'. S2: Acme finance memo, 3 pp., Feb 2026: p2 'our 2025 annual-plan pilot lifted cash collected up front by $210k'; p3 'net revenue retention unchanged'. S3: transcript, Northwind sales lead, 22 min: 08:40 'customers ask for annual all the time'; 15:10 'the big deals want 25% off'. Question: what discount, if any, should we offer?",
+      "assertions": [
+        "Every claim carries a citation with a source id and a location such as [S1:p12] or [S3:08:40]",
+        "Findings are organised by theme or sub-question, not as a source-by-source summary",
+        "Agreement and disagreement are explicit, naming which sources sit on each side (for example S1's 17% median vs S3's 25% ask)",
+        "Each finding has an evidence-strength rating and names the criteria behind it",
+        "The self-selection caveat on S1's churn figure is kept rather than turned into a causal claim",
+        "Lists gaps and what the sources do not say, such as no source testing a specific discount level on Northwind's own customers",
+        "Does not add facts, benchmarks or figures that are not in the three sources, unless tagged [outside]",
+        "Runs or recommends the citation checker and reports its result"
+      ]
+    }
+  ]
+}