skilldrop-cli 0.16.3__py3-none-any.whl

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

@@ -0,0 +1,146 @@
+# Worked example — four sources on a four-day week
+
+## Input given to the skill
+
+> Acme is thinking about moving our 14-person support team to a four-day week. Can you
+> synthesise these four sources? I've pasted the relevant pages below.
+>
+> 1. Northwind People Team, "Four-day week pilot: final report" (internal, Feb 2026, 18 pp.).
+>    Excerpts: p3 "The pilot ran for six months with 60 staff." p6 "Tickets closed per person
+>    fell 2% against the prior six months." p9 "Self-reported burnout fell from 41% to 22%."
+>    p11 "Sick days fell 30%." p12, Table 3: support team first-response time up 9%.
+> 2. Contoso Research, "Shorter Weeks 2026" (survey of 1,200 managers, Mar 2026, 32 pp.).
+>    p7 "63% of managers at firms trialling shorter weeks say productivity was maintained or
+>    improved." p14 "18% report coverage problems in customer-facing teams."
+> 3. Transcript of my interview with our support team lead, 12 Mar 2026, 41 min.
+>    00:14:20 "Fridays the queue builds up, Monday is brutal." 00:22:05 "Honestly the team is
+>    happier." 00:31:40 "If we do it, I'd want people to take different days off."
+> 4. Fabrikam News, "Four-day week works, says survey" (Apr 2026). Paragraph 2 reports the
+>    Contoso survey's 63% figure.
+
+---
+
+## First draft, checked
+
+The first draft went through the checker before it was shown to the user:
+
+```bash
+python3 scripts/citations.py synthesis.md
+```
+
+```
+# Citation check: synthesis-v1.md
+
+Sources: 4  ·  Claims checked: 12  ·  Errors: 4  ·  Warnings: 1  ·  Result: FAIL
+
+## Errors: citations that do not resolve (1)
+
+- line 49: [S1:p3; S5:p2] — no source S5 in the list
+
+## Errors: malformed citations (1)
+
+- line 48: [S1, S3] — write one id per part, separated by ';', e.g. [S1:p4; S2:p7]
+
+## Errors: uncited claims (2)
+
+- line 33: "The usual fix is a staggered rota so the desk is covered five days a week."
+- line 48: "- No source measures customer satisfaction scores, only response times [S1, S3]."
+
+## Warnings: citations with no location (1)
+
+- line 44: [S2] — add a page, section or timestamp
+
+## Warnings: sources never cited (0)
+
+None.
+
+## Info: [outside] claims to check by hand (0)
+
+None.
+```
+
+What each error meant:
+
+- **Line 33** was a sentence from memory ("The usual fix is a staggered rota…"). No source
+  says it. It was cut; the team lead's suggestion at 00:31:40 already sits, cited, under
+  "What the sources do not say", with the note that nothing tests it.
+- **Lines 48–49** had a malformed citation and a typo'd id (S5). Fixed to
+  `[S1:p12; S3:00:14:20]` and `[S1:p3]`.
+- **Line 44** cited S2 with no page. Fixed to `[S2:p14]`.
+
+After the fixes the checker reports:
+
+```
+Sources: 4  ·  Claims checked: 11  ·  Errors: 0  ·  Warnings: 0  ·  Result: PASS
+```
+
+S4 is cited once, and only to record that it repeats S2. That is deliberate: the register
+counts it with S2, so F1 rests on two lines of evidence, not three.
+
+---
+
+## Output: the synthesis as delivered
+
+# Synthesis: four-day week for Acme's support team
+
+_Prepared 2026-04-20 · 4 sources (3 independent) · Question from the user_
+
+## Question
+
+Should Acme move its 14-person support team to a four-day week? Sub-questions: does output hold up, does wellbeing improve, and what happens to customer response times?
+
+## Bottom line
+
+Output held roughly steady and burnout fell in the one controlled pilot [S1:p6; S1:p9], and a manager survey points the same way on output [S2:p7]. The clear cost is customer coverage: response times rose in the pilot's support team [S1:p12] and Acme's own team lead describes a Monday backlog [S3:00:14:20]. The evidence on output is moderate; on coverage it is limited but consistent.
+
+## Findings
+
+### F1. Output per person held roughly steady
+
+In Northwind's six-month pilot of 60 staff, tickets closed per person fell 2% against the prior six months [S1:p6]. In the Contoso survey, 63% of managers at firms trialling shorter weeks said productivity was maintained or improved [S2:p7].
+
+**Agreement:** S1 and S2 agree. S4 reports S2's survey and is counted with it [S4:para 2].
+**Strength:** moderate. Criteria: one primary pilot with a before-and-after baseline, plus one self-reported survey.
+
+### F2. Burnout and sick days fell
+
+Self-reported burnout fell from 41% to 22% over the pilot [S1:p9], and sick days fell 30% [S1:p11]. Acme's team lead says the team is happier on the trial schedule [S3:00:22:05].
+
+**Agreement:** S1 and S3 agree; no source disagrees.
+**Strength:** moderate. Criteria: primary data, but burnout is self-reported and S3 is one person's view.
+
+### F3. Customer response times got worse in support roles
+
+First-response time in the pilot's support team rose 9% [S1:p12, Table 3]. Of managers surveyed, 18% reported coverage problems in customer-facing teams [S2:p14]. The team lead says the queue builds up on Fridays and Mondays are hard [S3:00:14:20].
+
+**Agreement:** S1, S2 and S3 agree.
+**Strength:** limited. Criteria: one support team in the pilot, a minority finding in a self-reported survey, and one interview.
+
+## Agreement and disagreement
+
+| Finding | Agree | Disagree | Likely reason for the split | Strength |
+|---|---|---|---|---|
+| F1 output | S1, S2 | none | — [S1:p6; S2:p7] | moderate |
+| F2 wellbeing | S1, S3 | none | — [S1:p9; S3:00:22:05] | moderate |
+| F3 coverage | S1, S2, S3 | none | the survey's 18% covers all customer-facing teams, not only support [S2:p14] | limited |
+
+## Gaps
+
+- No source measures customer satisfaction scores, only response times [S1:p12; S3:00:14:20].
+- No source follows a team beyond six months [S1:p3].
+
+## What the sources do not say
+
+- The pilot reports output held steady; it doesn't say whether ticket complexity changed over the period [S1:p6].
+- The team lead suggests staggered days off [S3:00:31:40]; no source tests whether a staggered rota fixes the coverage gap.
+
+## Outside the sources
+
+- None. <!-- no-cite -->
+
+## Sources
+
+- S1: Northwind People Team, "Four-day week pilot: final report", internal report, Feb 2026, 18 pp. Before-and-after, 60 staff, six months.
+- S2: Contoso Research, "Shorter Weeks 2026", industry survey, Mar 2026, 32 pp. 1,200 managers, self-reported.
+- S3: Interview transcript, Acme support team lead, 12 Mar 2026, 41 min.
+- S4: Fabrikam News, "Four-day week works, says survey", news article, Apr 2026. Reports S2's survey; counted with S2.

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

@@ -0,0 +1,42 @@
+{
+  "name": "source-synthesis",
+  "version": "0.1.0",
+  "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\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brief-intake",
+    "decision-log",
+    "doc-critique",
+    "hypothesis-comparison",
+    "research-plan",
+    "strategy-analysis"
+  ],
+  "handoff": [
+    {
+      "to": "hypothesis-comparison",
+      "when": "the findings point to several rival explanations for the same observation",
+      "purpose": "Rank the explanations by how much of the cited evidence contradicts each.",
+      "fallback": "If hypothesis-comparison is absent, list the rival explanations under the findings with the citations for and against each, and say which has the least evidence against it."
+    }
+  ],
+  "tags": [
+    "research",
+    "synthesis",
+    "literature-review",
+    "citations",
+    "evidence"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
+  "model": {
+    "tier": "standard",
+    "rationale": "Bounded synthesis over supplied text with a fixed citation format and strength criteria; the citation checker catches the mechanical failures, so mid-tier judgment is enough."
+  }
+}

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

@@ -0,0 +1,92 @@
+# source-synthesis — reference
+
+## Citation format
+
+One bracket per claim, one or more parts separated by `;`. Each part is a source id, a colon,
+and a location.
+
+| Source type | Location | Example |
+|---|---|---|
+| Paginated document | page or page range | `[S1:p4]`, `[S1:pp4-6]` |
+| Document with numbered sections | section | `[S2:§3.2]` |
+| Report with figures or tables | table or figure | `[S3:Table 2]` |
+| Transcript or recording | timestamp | `[S4:00:12:30]` |
+| Web page with no pages | heading | `[S5:"Results" section]` |
+| Several sources | parts joined by `;` | `[S1:p4; S3:§2.1]` |
+
+Don't write `[S1, S2]`: the checker flags it as malformed, because it can't tell which
+location belongs to which source. Use `[outside]` for anything that doesn't come from the
+supplied sources.
+
+The sources list sits under a `## Sources` heading, one per line, starting with the id:
+
+```
+## Sources
+
+- S1: Northwind People Team, "Four-day week pilot: final report", internal report, Jun 2026, 18 pp.
+- S2: Interview transcript, Acme support team lead, 12 Mar 2026, 41 min.
+```
+
+## Evidence strength
+
+Rate each finding on what supports it, not on how plausible it sounds. Use the criteria below
+and name the ones that decided the rating.
+
+| Criterion | Stronger | Weaker |
+|---|---|---|
+| Independent sources | Several sources with separate data | One source, or several repeating one dataset |
+| Source type | Primary data: study, dataset, controlled pilot, transcript | Commentary, opinion, news report of someone else's work |
+| Method | Comparison group, before-and-after with a baseline, stated sample | Anecdote, self-report with no baseline, method not stated |
+| Sample size | Large enough for the claim, and stated | Small or not stated |
+| Recency | Current for the question | Old enough that conditions have changed |
+| Directness | Measures the thing asked about | Measures a proxy or a different population |
+| Agreement | Sources agree | Sources conflict without an explanation |
+
+Ratings:
+
+- **Strong:** two or more independent primary sources with sound methods agree, and none
+  credibly disagrees.
+- **Moderate:** one sound primary source, or several weaker sources that agree.
+- **Limited:** one weak source, self-report only, a proxy measure, or commentary only.
+- **Conflicting:** credible sources disagree and the sources don't explain why.
+
+For health and clinical questions, fields use formal systems such as GRADE to rate certainty
+of evidence. If the user works in such a field, ask whether they need that system instead of
+the simple scale here.
+
+## Handling disagreement
+
+1. Check whether the sources measure the same thing: same definition, population, period and
+   unit. Many "disagreements" are different questions.
+2. If they do, look for a difference in method or sample that would explain the split, and
+   name it if a source states it.
+3. If nothing explains it, rate the finding **conflicting** and report both sides with their
+   citations. Don't pick the side you find more plausible without saying why.
+
+## Independence
+
+Count sources by line of evidence, not by document:
+
+- A news article reporting a survey is the survey, not a second source.
+- Two reports by the same team on the same data are one line of evidence.
+- Interviews with people in the same team can share one view; say so if the transcripts show it.
+
+Note dependencies in the source register: "S4 reports S1's survey; counted with S1."
+
+## Common distortions
+
+- **Hedge loss:** "may", "in this sample", "associated with" dropped in the summary.
+- **Scope creep:** a finding about one company or country stated as a general truth.
+- **Selective citing:** quoting the part of a source that agrees and skipping its caveats or
+  limitations section.
+- **Number drift:** rounding or converting a figure (relative to absolute, monthly to yearly)
+  without saying so.
+- **Outside leakage:** adding a well-known figure from memory because it "fits". Tag it
+  `[outside]` or leave it out.
+
+## What "what the sources do not say" means
+
+Gaps are questions the user cares about that the sources don't answer. "What the sources do
+not say" also covers inferences a reader is likely to draw that the sources don't support.
+✅ *"The pilot reports output held steady; it doesn't say whether customers noticed slower
+replies."* This section stops the synthesis from being read as more than it is.

skilldrop_cli/data/packs/research/skills/source-synthesis/scripts/citations.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Check the citations in a source synthesis draft.
+
+Every claim in a synthesis should cite a supplied source and a location in it,
+written as [S1:p4], [S2:§3.2], [S3:00:12:30], or several at once as
+[S1:p4; S2:p7]. Facts from outside the supplied sources are tagged [outside].
+
+This script reads the draft and a sources list and reports:
+  - citations whose source id is not in the sources list   (error)
+  - malformed citations, such as [S1, S2]                  (error)
+  - paragraphs, list items and table rows with no citation (error)
+  - citations with no location, such as a bare [S1]        (warning)
+  - sources that are never cited                           (warning)
+  - [outside] tags, which a reader should check            (info)
+
+Not checked as claims: headings, the Sources and Question sections, a line that
+is all italics (such as a "Prepared ..." line), units shorter than --min-words,
+units that start with a bold label such as **Strength:** or **Agreement:**
+(change with --label), and any unit containing <!-- no-cite -->.
+  - how many times each source is cited                    (info)
+
+The sources list is either a separate file (--sources) or a "## Sources"
+section inside the draft. Each source is one line that starts with its id:
+    S1: Northwind pilot report, Q2 2026 (internal, 18 pp.)
+    - [S2] Interview transcript, Acme support lead, 12 Mar 2026
+
+Usage:
+    python3 citations.py draft.md
+    python3 citations.py draft.md --sources sources.md -o report.md
+    python3 citations.py draft.md --strict --json
+
+Exit codes: 0 no errors (warnings allowed unless --strict), 1 errors found,
+2 bad input (missing file, no sources found, duplicate source ids).
+"""
+
+import argparse
+import json
+import re
+import sys
+from collections import OrderedDict
+from pathlib import Path
+
+SOURCE_LINE = re.compile(r"^\s*(?:[-*+]\s+)?\[?(S\d+)\]?\s*[:.)\]\-—–]\s*(\S.*)$")
+BRACKET = re.compile(r"\[([^\[\]]+)\](?!\()")
+CITE_PART = re.compile(r"^\s*(S\d+)\s*(?::\s*(.*?))?\s*$")
+LOOKS_LIKE_CITE = re.compile(r"^\s*S\d+\b")
+OUTSIDE = re.compile(r"\[outside\]", re.IGNORECASE)
+NO_CITE = "<!-- no-cite -->"
+HEADING = re.compile(r"^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$")
+LIST_ITEM = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+")
+TABLE_SEP = re.compile(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$")
+RULE = re.compile(r"^\s*([-*_])(\s*\1){2,}\s*$")
+
+DEFAULT_SKIP = ["sources", "references", "bibliography", "source list"]
+CLAIM_FREE_SECTIONS = ["question", "questions", "research question"]
+DEFAULT_LABELS = ["agreement", "strength", "confidence"]
+ITALIC_LINE = re.compile(r"^\s*(_[^_].*_|\*[^*].*\*)\s*$")
+LABEL = re.compile(r"^\s*(?:[-*+]\s+)?\*\*([^*:]+):?\*\*")
+
+
+def fail(msg):
+    sys.stderr.write("error: " + msg + "\n")
+    sys.exit(2)
+
+
+def read_text(path):
+    p = Path(path)
+    if not p.is_file():
+        fail("file not found: " + str(path))
+    try:
+        return p.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        fail("not a UTF-8 text file: " + str(path))
+    return ""
+
+
+def parse_sources(lines):
+    """Return an ordered dict id -> description, and a list of duplicate ids."""
+    sources = OrderedDict()
+    dupes = []
+    for line in lines:
+        m = SOURCE_LINE.match(line)
+        if not m:
+            continue
+        sid, desc = m.group(1), m.group(2).strip()
+        if sid in sources:
+            dupes.append(sid)
+        else:
+            sources[sid] = desc
+    return sources, dupes
+
+
+def split_sections(text):
+    """Yield (heading_title_lower, [lines]) blocks; the first block has title ''."""
+    title = ""
+    block = []
+    in_code = False
+    for line in text.splitlines():
+        if line.strip().startswith("```"):
+            in_code = not in_code
+            block.append(line)
+            continue
+        m = None if in_code else HEADING.match(line)
+        if m:
+            yield title, block
+            title = m.group(2).strip().lower()
+            block = []
+        else:
+            block.append(line)
+    yield title, block
+
+
+def units(lines, start_line):
+    """Split body lines into checkable units: paragraphs, list items, table rows.
+
+    Returns a list of (line_number, text).
+    """
+    out = []
+    current = []
+    current_start = None
+    in_code = False
+
+    def flush():
+        if current:
+            out.append((current_start, " ".join(s.strip() for s in current)))
+
+    for offset, line in enumerate(lines):
+        n = start_line + offset
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            flush()
+            current, current_start = [], None
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+        if not stripped or RULE.match(line) or (stripped.startswith(">") and not stripped.strip("> ")):
+            flush()
+            current, current_start = [], None
+            continue
+        if stripped.startswith("|"):
+            flush()
+            current, current_start = [], None
+            if TABLE_SEP.match(line):
+                # The row above a separator is the table's header, not a claim.
+                if out and out[-1][1].startswith("|"):
+                    out.pop()
+            else:
+                out.append((n, stripped))
+            continue
+        if LIST_ITEM.match(line):
+            flush()
+            current, current_start = [line], n
+            continue
+        if not current:
+            current_start = n
+        current.append(line)
+    flush()
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Check [S1:p4]-style citations in a synthesis draft.")
+    ap.add_argument("draft", help="the draft, as markdown or plain text")
+    ap.add_argument("--sources", help="a file listing sources, one per line as 'S1: ...'. "
+                                      "Default: the draft's own '## Sources' section")
+    ap.add_argument("--skip-section", action="append", default=[],
+                    help="a heading whose body needs no citations (repeatable). "
+                         "Sources/References are always skipped")
+    ap.add_argument("--label", action="append", default=None,
+                    help="a bold label, such as Strength, whose unit is a judgment, not a "
+                         "claim (repeatable). Default: Agreement, Strength, Confidence")
+    ap.add_argument("--min-words", type=int, default=6,
+                    help="units shorter than this are treated as labels, not claims (default 6)")
+    ap.add_argument("--strict", action="store_true", help="treat warnings as errors")
+    ap.add_argument("--json", action="store_true", help="write the report as JSON")
+    ap.add_argument("-o", "--output", help="write the report here instead of stdout")
+    args = ap.parse_args()
+
+    if args.min_words < 0:
+        fail("--min-words must be zero or more")
+
+    text = read_text(args.draft)
+    skip = set(DEFAULT_SKIP) | set(CLAIM_FREE_SECTIONS) | set(x.strip().lower() for x in args.skip_section)
+    labels = set(x.strip().lower() for x in (args.label if args.label is not None else DEFAULT_LABELS))
+
+    # Sources
+    if args.sources:
+        sources, dupes = parse_sources(read_text(args.sources).splitlines())
+        where = args.sources
+    else:
+        src_lines = []
+        for title, block in split_sections(text):
+            if title in DEFAULT_SKIP:
+                src_lines.extend(block)
+        sources, dupes = parse_sources(src_lines)
+        where = "the draft's Sources section"
+    if not sources:
+        fail("no sources found in " + where + ". List each one on its own line as 'S1: description'.")
+    if dupes:
+        fail("duplicate source ids in " + where + ": " + ", ".join(sorted(set(dupes))))
+
+    # Walk the body
+    unresolved, malformed, uncited, no_location, outside = [], [], [], [], []
+    counts = OrderedDict((sid, 0) for sid in sources)
+    checked = 0
+    line_no = 1
+    for title, block in split_sections(text):
+        start = line_no + (0 if title == "" else 1)
+        line_no = start + len(block)
+        if title in skip:
+            continue
+        for n, unit in units(block, start):
+            cited = False
+            for m in BRACKET.finditer(unit):
+                inner = m.group(1)
+                if not LOOKS_LIKE_CITE.match(inner):
+                    continue
+                for part in inner.split(";"):
+                    pm = CITE_PART.match(part)
+                    if not pm:
+                        malformed.append((n, "[" + inner + "]"))
+                        continue
+                    sid, loc = pm.group(1), (pm.group(2) or "").strip()
+                    if sid not in sources:
+                        unresolved.append((n, "[" + inner + "]", sid))
+                        continue
+                    cited = True
+                    counts[sid] += 1
+                    if not loc:
+                        no_location.append((n, "[" + inner + "]"))
+            if OUTSIDE.search(unit):
+                outside.append((n, unit))
+                cited = True
+            if NO_CITE in unit or ITALIC_LINE.match(unit):
+                continue
+            lm = LABEL.match(unit)
+            if lm and lm.group(1).strip().lower() in labels:
+                continue
+            words = len(re.findall(r"[A-Za-z0-9']+", BRACKET.sub(" ", unit)))
+            if words < args.min_words:
+                continue
+            checked += 1
+            if not cited:
+                uncited.append((n, unit))
+
+    unused = [sid for sid, c in counts.items() if c == 0]
+    errors = len(unresolved) + len(malformed) + len(uncited)
+    warnings = len(no_location) + len(unused)
+    failed = errors > 0 or (args.strict and warnings > 0)
+
+    if args.json:
+        report = json.dumps({
+            "draft": args.draft,
+            "sources": len(sources),
+            "units_checked": checked,
+            "errors": errors,
+            "warnings": warnings,
+            "passed": not failed,
+            "unresolved": [{"line": n, "citation": c, "source": s} for n, c, s in unresolved],
+            "malformed": [{"line": n, "citation": c} for n, c in malformed],
+            "uncited": [{"line": n, "text": t} for n, t in uncited],
+            "no_location": [{"line": n, "citation": c} for n, c in no_location],
+            "unused_sources": unused,
+            "outside": [{"line": n, "text": t} for n, t in outside],
+            "citations_per_source": counts,
+        }, indent=2) + "\n"
+    else:
+        def short(t, k=90):
+            return t if len(t) <= k else t[:k - 3] + "..."
+        out = ["# Citation check: " + Path(args.draft).name, ""]
+        out.append("Sources: {}  ·  Claims checked: {}  ·  Errors: {}  ·  Warnings: {}  ·  Result: {}".format(
+            len(sources), checked, errors, warnings, "FAIL" if failed else "PASS"))
+        out.append("")
+        def section(title, rows):
+            out.append("## " + title + " (" + str(len(rows)) + ")")
+            out.append("")
+            if rows:
+                out.extend(rows)
+            else:
+                out.append("None.")
+            out.append("")
+        section("Errors: citations that do not resolve",
+                ["- line {}: {} — no source {} in the list".format(n, c, s) for n, c, s in unresolved])
+        section("Errors: malformed citations",
+                ["- line {}: {} — write one id per part, separated by ';', e.g. [S1:p4; S2:p7]".format(n, c)
+                 for n, c in malformed])
+        section("Errors: uncited claims",
+                ["- line {}: \"{}\"".format(n, short(t)) for n, t in uncited])
+        section("Warnings: citations with no location",
+                ["- line {}: {} — add a page, section or timestamp".format(n, c) for n, c in no_location])
+        section("Warnings: sources never cited",
+                ["- {}: {}".format(s, short(sources[s], 70)) for s in unused])
+        section("Info: [outside] claims to check by hand",
+                ["- line {}: \"{}\"".format(n, short(t)) for n, t in outside])
+        out.append("## Citations per source")
+        out.append("")
+        out.append("| Source | Citations |")
+        out.append("|---|---|")
+        for sid, c in counts.items():
+            out.append("| {} | {} |".format(sid, c))
+        report = "\n".join(out) + "\n"
+
+    if args.output:
+        Path(args.output).write_text(report, encoding="utf-8")
+        sys.stdout.write("wrote {} — {}, {} error(s), {} warning(s)\n".format(
+            args.output, "FAIL" if failed else "PASS", errors, warnings))
+    else:
+        sys.stdout.write(report)
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,46 @@
+# Synthesis: {question, in a few words}
+
+_Prepared {YYYY-MM-DD} · {N} sources · Question from {the user / research plan}_
+
+## Question
+
+{The question, and the sub-questions if there are any.}
+
+## Bottom line
+
+{Three sentences or fewer, each with citations. Say how strong the evidence is overall.}
+
+## Findings
+
+### F1. {One-sentence finding, no stronger than its weakest source}
+
+{Two to four sentences of detail, each claim cited: [S1:p4; S3:§2.1].}
+
+**Agreement:** {S1, S3 agree; S2 disagrees because … [S2:p9]}
+**Strength:** {strong / moderate / limited / conflicting}. Criteria: {the ones that decided it}.
+
+### F2. …
+
+## Agreement and disagreement
+
+| Finding | Agree | Disagree | Likely reason for the split | Strength |
+|---|---|---|---|---|
+| F1 | S1, S3 | S2 | {different population, period, definition, or "not explained"} [S2:p9] | moderate |
+
+## Gaps
+
+- {A sub-question no source answers.}
+- {A population, period or region no source covers.}
+
+## What the sources do not say
+
+- {An inference a reader might draw that the sources don't support.}
+
+## Outside the sources
+
+- {Each [outside] claim, or "None."} <!-- no-cite -->
+
+## Sources
+
+- S1: {author or owner}, "{title}", {type}, {date}, {pages or length}. {Method and sample if stated.} {Dependencies, or "never cited because …".}
+- S2: …