@diottodev/runic 1.0.0 → 1.1.0

package/research/dossier/skills/dossier/scripts/disconfirming_evidence_balance.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""disconfirming_evidence_balance.py — Enforce ≥30% disconfirming search budget.
+
+Stdlib-only. The dossier skill's non-negotiable: ≥30% of Phase 4 searches must
+be classified as disconfirming (would refute the hypothesis if results favorable).
+
+Reads from a dossier session JSON (created by `citation_tracker.py`) and:
+  - Returns PASS if disconfirming_ratio >= 0.30
+  - Returns WARN if 0.20 <= ratio < 0.30 (recoverable; surface to user)
+  - Returns FAIL if ratio < 0.20 (confirmation bias; halt + remediate)
+
+Outputs suggested disconfirming queries to add (based on antonym-pivot heuristic
+from references/hypothesis_testing_discipline.md).
+
+NO LLM CALLS. Pure ratio math + heuristic suggestions.
+
+Usage:
+    python disconfirming_evidence_balance.py --session dossier-MS-20260515
+    python disconfirming_evidence_balance.py --session ... --output json
+    python disconfirming_evidence_balance.py --sample
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+SESSIONS_DIR = Path.home() / ".dossier_sessions"
+MIN_RATIO = 0.30
+WARN_RATIO = 0.20
+
+
+# Antonym-pivot heuristics for constructing disconfirming queries
+DISCONFIRMING_PIVOTS = {
+    "consolidating": ["diversifying", "splitting", "decentralizing"],
+    "growing": ["shrinking", "declining", "stagnating"],
+    "winning": ["losing", "failing", "underperforming"],
+    "successful": ["failed", "unsuccessful", "struggling"],
+    "expanding": ["contracting", "exiting", "retreating from"],
+    "strong": ["weak", "missing"],
+    "leading": ["trailing", "lagging"],
+    "innovating": ["copying", "lagging behind"],
+    "investing in": ["divesting", "exiting"],
+    "hiring": ["laying off", "departures from"],
+}
+
+
+def suggest_disconfirming_queries(hypothesis: str, supporting_queries: List[str]) -> List[str]:
+    """Heuristic: for each supporting term, suggest antonym-pivoted disconfirming."""
+    suggestions: List[str] = []
+    hyp_lower = hypothesis.lower()
+    for pivot, antonyms in DISCONFIRMING_PIVOTS.items():
+        if pivot in hyp_lower:
+            for antonym in antonyms[:2]:  # first 2 only to avoid noise
+                disconfirming = hyp_lower.replace(pivot, antonym)
+                suggestions.append(disconfirming)
+    if not suggestions:
+        # Generic fallback patterns
+        suggestions.append(f"counter-evidence to: {hypothesis}")
+        suggestions.append(f"critics of {hypothesis}")
+        suggestions.append(f"failures contradicting {hypothesis}")
+    return suggestions[:5]
+
+
+def analyze(session_data: Dict[str, Any]) -> Dict[str, Any]:
+    c = session_data.get("counts", {})
+    total = c.get("searches", 0)
+    supporting = c.get("supporting_searches", 0)
+    disconfirming = c.get("disconfirming_searches", 0)
+    inconclusive = c.get("inconclusive_searches", 0)
+
+    if total == 0:
+        return {
+            "verdict": "INSUFFICIENT_DATA",
+            "ratio": 0.0,
+            "total_searches": 0,
+            "supporting": 0,
+            "disconfirming": 0,
+            "inconclusive": 0,
+            "rule_floor": MIN_RATIO,
+            "message": "No searches recorded yet. Run Phase 4 first.",
+            "remediation_needed": False,
+        }
+
+    ratio = disconfirming / total
+    needed_disconfirming = max(0, int((MIN_RATIO * total) - disconfirming + 0.999))  # ceiling
+
+    if ratio >= MIN_RATIO:
+        verdict = "PASS"
+        message = f"Disconfirming ratio {ratio:.0%} meets ≥{MIN_RATIO:.0%} floor. Decision-grade balance OK."
+        remediation_needed = False
+        suggested = []
+    elif ratio >= WARN_RATIO:
+        verdict = "WARN"
+        message = (
+            f"Disconfirming ratio {ratio:.0%} is below ≥{MIN_RATIO:.0%} floor "
+            f"but above {WARN_RATIO:.0%} threshold. Recoverable — add {needed_disconfirming} "
+            f"disconfirming queries to reach floor."
+        )
+        remediation_needed = True
+        suggested = suggest_disconfirming_queries(
+            session_data.get("hypothesis", ""),
+            [s["query"] for s in session_data.get("searches", []) if s.get("classification") == "supporting"]
+        )
+    else:
+        verdict = "FAIL"
+        message = (
+            f"Disconfirming ratio {ratio:.0%} below {WARN_RATIO:.0%} — confirmation bias risk is real. "
+            f"HALT + add {needed_disconfirming} disconfirming queries before generating DOCX. "
+            f"A SUPPORTED verdict at this ratio is not credible."
+        )
+        remediation_needed = True
+        suggested = suggest_disconfirming_queries(
+            session_data.get("hypothesis", ""),
+            [s["query"] for s in session_data.get("searches", []) if s.get("classification") == "supporting"]
+        )
+
+    return {
+        "verdict": verdict,
+        "ratio": ratio,
+        "rule_floor": MIN_RATIO,
+        "total_searches": total,
+        "supporting": supporting,
+        "disconfirming": disconfirming,
+        "inconclusive": inconclusive,
+        "disconfirming_needed_to_reach_floor": needed_disconfirming,
+        "message": message,
+        "remediation_needed": remediation_needed,
+        "suggested_disconfirming_queries": suggested,
+    }
+
+
+SAMPLE_SESSION = {
+    "session": "sample-dossier",
+    "subject": "Microsoft",
+    "hypothesis": "Microsoft is consolidating AI spend on Foundry platform",
+    "counts": {
+        "searches": 10,
+        "supporting_searches": 8,
+        "disconfirming_searches": 2,
+        "inconclusive_searches": 0,
+    },
+    "searches": [
+        {"query": "Microsoft Foundry adoption 2026", "classification": "supporting"},
+        {"query": "Microsoft AI consolidation strategy", "classification": "supporting"},
+    ],
+}
+
+
+def render_human(result: Dict[str, Any]) -> str:
+    out: List[str] = []
+    out.append(f"Disconfirming evidence balance: {result['verdict']}")
+    out.append(f"  Total searches:                  {result['total_searches']}")
+    out.append(f"  Supporting:                      {result['supporting']}")
+    out.append(f"  Disconfirming:                   {result['disconfirming']}")
+    out.append(f"  Inconclusive:                    {result['inconclusive']}")
+    out.append(f"  Ratio (disconfirming/total):     {result['ratio']:.0%}")
+    out.append(f"  Rule floor:                      {result['rule_floor']:.0%}")
+    if result.get('disconfirming_needed_to_reach_floor', 0) > 0:
+        out.append(f"  Disconfirming queries to add:    {result['disconfirming_needed_to_reach_floor']}")
+    out.append("")
+    out.append(result["message"])
+    if result.get("suggested_disconfirming_queries"):
+        out.append("")
+        out.append("Suggested disconfirming queries (antonym-pivot from hypothesis):")
+        for q in result["suggested_disconfirming_queries"]:
+            out.append(f"  - {q}")
+    return "\n".join(out)
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--session", help="Session name (in ~/.dossier_sessions/)")
+    parser.add_argument("--sample", action="store_true", help="Analyze embedded sample data (10 searches, 80% supporting)")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    if args.sample:
+        data = SAMPLE_SESSION
+    elif args.session:
+        p = SESSIONS_DIR / f"{args.session}.json"
+        if not p.exists():
+            print(f"error: session not found at {p}", file=sys.stderr); return 2
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            print(f"error: invalid session JSON: {e}", file=sys.stderr); return 2
+    else:
+        parser.print_help(); return 0
+
+    result = analyze(data)
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(render_human(result))
+
+    if result["verdict"] == "FAIL":
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/research/dossier/skills/dossier/scripts/source_tier_classifier.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""source_tier_classifier.py — URL → primary/secondary/tertiary tier.
+
+Stdlib-only. Classifies a source URL into reliability tier based on domain
+heuristics. The dossier skill uses tier on every flag in the DOCX so reviewers
+can calibrate confidence.
+
+Tiers:
+  - PRIMARY:    Official, regulatory, court records, SEC EDGAR, .gov, company
+                official site, academic publications (peer-reviewed)
+  - SECONDARY:  Mainstream news (NYT, WSJ, Reuters), trade press, established
+                publications (TechCrunch, The Information, Stratechery)
+  - TERTIARY:   Blogs, forums, social media, user-generated content (Reddit, HN,
+                Glassdoor, Medium, personal blogs)
+
+NO LLM CALLS. Pure domain pattern matching.
+
+Usage:
+    python source_tier_classifier.py --url "https://www.sec.gov/cgi-bin/browse-edgar?..."
+    python source_tier_classifier.py --url "https://news.ycombinator.com/item?id=..."
+    python source_tier_classifier.py --sample
+"""
+
+import argparse
+import json
+import re
+import sys
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+
+# Pattern-based tier assignment. Most specific patterns first.
+
+PRIMARY_DOMAIN_EXACT = {
+    "sec.gov", "data.sec.gov", "www.sec.gov",
+    "courtlistener.com", "pacer.gov",
+    "uspto.gov", "patents.google.com",  # patents.google.com indexes USPTO data
+    "fda.gov", "cdc.gov", "nih.gov", "grants.nih.gov", "reporter.nih.gov",
+    "federalregister.gov", "regulations.gov",
+    "gao.gov", "oig.gov",
+    "irs.gov",
+    "sec.org",  # generic .org for SEC alternates
+}
+
+PRIMARY_DOMAIN_SUFFIX = [
+    ".gov",  # any government domain
+    ".mil",  # military
+    ".edu",  # academic (caveat: some .edu content is tertiary, but most institutional pages are primary)
+]
+
+PRIMARY_DOMAIN_CONTAINS = [
+    "projects.propublica.org/nonprofits",  # ProPublica Nonprofit Explorer (free Form 990 access)
+]
+
+# Academic publication primary sources
+PRIMARY_ACADEMIC = {
+    "nature.com", "science.org", "nejm.org", "thelancet.com", "jamanetwork.com",
+    "pnas.org", "bmj.com", "cell.com", "plos.org",
+    "scholar.google.com",  # indexes peer-reviewed; treat as primary
+}
+
+# Mainstream news (secondary)
+SECONDARY_NEWS = {
+    "nytimes.com", "wsj.com", "ft.com", "reuters.com", "ap.org", "apnews.com",
+    "bbc.com", "bbc.co.uk", "theguardian.com", "economist.com",
+    "washingtonpost.com", "latimes.com", "bloomberg.com",
+    "cnbc.com", "abcnews.go.com", "nbcnews.com", "cbsnews.com",
+}
+
+# Trade press / established tech publications (secondary)
+SECONDARY_TRADE = {
+    "techcrunch.com", "theverge.com", "wired.com", "arstechnica.com",
+    "theinformation.com", "stratechery.com",
+    "axios.com", "politico.com",
+    "forbes.com",  # mixed quality, but generally secondary
+    "modernhealthcare.com", "healthcareitnews.com",
+    "law360.com", "natlawreview.com",
+}
+
+# Trade-press journalism orgs (secondary)
+SECONDARY_INVESTIGATIVE = {
+    "propublica.org", "icij.org",  # ProPublica investigative reporting (separate from Nonprofit Explorer)
+}
+
+# Tertiary indicators
+TERTIARY_DOMAIN_EXACT = {
+    "reddit.com", "old.reddit.com", "news.ycombinator.com",
+    "medium.com", "dev.to", "substack.com",
+    "twitter.com", "x.com",
+    "linkedin.com",  # public posts; profiles separately primary for the subject
+    "glassdoor.com", "indeed.com", "comparably.com",
+    "quora.com", "stackoverflow.com",
+    "facebook.com", "instagram.com", "tiktok.com",
+}
+
+TERTIARY_PATTERN = [
+    re.compile(r".*\.medium\.com$"),
+    re.compile(r".*\.substack\.com$"),
+    re.compile(r".*\.blogspot\.com$"),
+    re.compile(r".*\.wordpress\.com$"),
+    re.compile(r".*\.tumblr\.com$"),
+]
+
+# Company-official site detection (primary IF the dossier subject)
+# Generic patterns:
+def is_likely_company_official(domain: str, subject_keywords: List[str]) -> bool:
+    """If the domain contains the subject's name and isn't a known news/blog, it's likely official."""
+    if not subject_keywords:
+        return False
+    domain_lower = domain.lower()
+    for kw in subject_keywords:
+        if kw.lower() in domain_lower:
+            return True
+    return False
+
+
+def classify(url: str, subject_keywords: Optional[List[str]] = None) -> Dict[str, Any]:
+    if not url or not url.strip():
+        return {"tier": "unknown", "url": url, "rationale": "Empty URL"}
+
+    try:
+        parsed = urlparse(url)
+    except Exception as e:
+        return {"tier": "unknown", "url": url, "rationale": f"URL parse failed: {e}"}
+
+    domain = parsed.netloc.lower()
+    # Strip 'www.' prefix for matching
+    if domain.startswith("www."):
+        domain_no_www = domain[4:]
+    else:
+        domain_no_www = domain
+
+    # Strip port if present
+    domain = domain.split(":")[0]
+    domain_no_www = domain_no_www.split(":")[0]
+
+    # Check exact-match tiers first
+    if domain in PRIMARY_DOMAIN_EXACT or domain_no_www in PRIMARY_DOMAIN_EXACT:
+        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} is in primary exact-match list (regulatory/court/official)"}
+
+    if domain in PRIMARY_ACADEMIC or domain_no_www in PRIMARY_ACADEMIC:
+        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} is a peer-reviewed academic publication"}
+
+    if domain in SECONDARY_NEWS or domain_no_www in SECONDARY_NEWS:
+        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is a mainstream news outlet"}
+
+    if domain in SECONDARY_TRADE or domain_no_www in SECONDARY_TRADE:
+        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is established trade press"}
+
+    if domain in SECONDARY_INVESTIGATIVE or domain_no_www in SECONDARY_INVESTIGATIVE:
+        return {"tier": "secondary", "url": url, "rationale": f"Domain {domain} is investigative journalism"}
+
+    if domain in TERTIARY_DOMAIN_EXACT or domain_no_www in TERTIARY_DOMAIN_EXACT:
+        return {"tier": "tertiary", "url": url, "rationale": f"Domain {domain} is user-generated content (forum/social/review)"}
+
+    # Pattern checks
+    for pattern in TERTIARY_PATTERN:
+        if pattern.match(domain):
+            return {"tier": "tertiary", "url": url, "rationale": f"Domain {domain} matches tertiary pattern (blog hosting platform)"}
+
+    # Suffix checks
+    for suffix in PRIMARY_DOMAIN_SUFFIX:
+        if domain.endswith(suffix):
+            return {"tier": "primary", "url": url, "rationale": f"Domain {domain} has primary-tier suffix '{suffix}'"}
+
+    # Contains checks
+    for pattern in PRIMARY_DOMAIN_CONTAINS:
+        if pattern in url.lower():
+            return {"tier": "primary", "url": url, "rationale": f"URL contains primary-tier pattern '{pattern}'"}
+
+    # Company-official heuristic (if subject keywords provided)
+    if subject_keywords and is_likely_company_official(domain, subject_keywords):
+        return {"tier": "primary", "url": url, "rationale": f"Domain {domain} appears to be the subject's official site (matches subject keywords)"}
+
+    # Default for unknown: secondary (give benefit of doubt to legitimate-looking news/site)
+    # But add a confidence note
+    return {
+        "tier": "secondary",
+        "url": url,
+        "rationale": f"Domain {domain} not in known lists; defaulting to secondary. Manual review recommended for high-stakes citations.",
+        "confidence": "low",
+    }
+
+
+SAMPLE_URLS = [
+    "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000789019",
+    "https://www.nytimes.com/2026/05/15/tech/microsoft-ai-strategy.html",
+    "https://techcrunch.com/2026/05/01/microsoft-acquires-startup-x/",
+    "https://news.ycombinator.com/item?id=123456",
+    "https://glassdoor.com/Reviews/Microsoft-Corp-E1651.htm",
+    "https://medium.com/@author/microsoft-foundry-deep-dive",
+    "https://www.microsoft.com/en-us/about",
+    "https://projects.propublica.org/nonprofits/organizations/123456789",
+    "https://scholar.google.com/scholar?q=...",
+    "https://www.federalregister.gov/documents/2026/05/01/...",
+    "https://random-blog-i-just-found.com/microsoft-rumor",
+]
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--url", help="URL to classify")
+    parser.add_argument("--subject", help="Subject keywords (comma-separated) for company-official heuristic")
+    parser.add_argument("--sample", action="store_true", help="Classify a batch of sample URLs")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    subject_kws = [s.strip() for s in args.subject.split(",")] if args.subject else None
+
+    if args.sample:
+        results = [classify(u, ["microsoft"]) for u in SAMPLE_URLS]
+        if args.output == "json":
+            print(json.dumps(results, indent=2))
+        else:
+            for r in results:
+                tier = r["tier"].upper()
+                marker = {"PRIMARY": "[1°]", "SECONDARY": "[2°]", "TERTIARY": "[3°]"}.get(tier, "[?]")
+                print(f"{marker} {tier:<10s} {r['url']}")
+                print(f"      {r['rationale']}")
+        return 0
+    elif args.url:
+        result = classify(args.url, subject_kws)
+        if args.output == "json":
+            print(json.dumps(result, indent=2))
+        else:
+            print(f"Tier:      {result['tier'].upper()}")
+            print(f"URL:       {result['url']}")
+            print(f"Rationale: {result['rationale']}")
+            if result.get("confidence"):
+                print(f"Confidence: {result['confidence']}")
+        return 0
+    else:
+        parser.print_help()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/research/grants/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "grants",
+  "description": "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope \u2014 non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake.",
+  "version": "2.9.0",
+  "author": {
+    "name": "Alireza Rezvani",
+    "url": "https://alirezarezvani.com"
+  },
+  "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/research/grants",
+  "repository": "https://github.com/alirezarezvani/claude-skills",
+  "license": "MIT",
+  "skills": [
+    "./skills/grants"
+  ],
+  "source": {
+    "spec": "megaprompts/08-grants-megaprompt.md",
+    "build_pattern": "Path B (direct conversion). Research-pack shape \u2014 sibling of pulse + litreview. Multi-source (Consensus + RePORTER POST + NOSI fetch) with DOCX output via Node.js docx library.",
+    "sibling_of": "research/litreview, research/pulse (pulse currently in engineering/ \u2014 cleanup PR queued)"
+  }
+}

package/research/grants/README.md

@@ -0,0 +1,54 @@
+# grants
+
+NIH grant research skill for clinical researchers. Produces a strategic NIH funding overview as an editable `.docx`:
+
+1. **Research positioning analysis** — 5-facet Consensus search producing gap quotes + draft Significance/Innovation language
+2. **Institute mapping** — Which NIH institutes are actually funding this area (via RePORTER)
+3. **Targeted grant discovery** — NOSIs, open FOAs, funded overlap filtered to mapped institutes
+4. **Strategic recommendations** — Career-stage + project-scope mechanism matching, program officer guidance, submission timeline
+
+## Sibling skill relationship
+
+Part of the **research pack** (sibling of `pulse`, `litreview`; future siblings: `patent`, `dossier`, `syllabus`). All share the Agent Integrity Rules block (1 q/sec, source discipline, three-count tracking, retry-once-after-3s, stop-after-3-consecutive-failures).
+
+**Different from `litreview`:**
+- Adds **RePORTER POST** queries (not just Consensus) — NIH-specific funded-project data
+- Adds **NOSI fetch** for `NOT-*` opportunity numbers
+- DOCX has 9 sections (vs 8 in litreview) — adds Strategic Recommendations + Study Sections sections
+- NIH-only scope; non-NIH funders out of scope
+
+## Source spec
+
+[`megaprompts/08-grants-megaprompt.md`](../../megaprompts/08-grants-megaprompt.md) (PR #657).
+
+## Plugin layout
+
+```
+research/grants/
+├── .claude-plugin/plugin.json
+├── README.md
+├── agents/cs-grants.md             ← NIH-funding persona, RePORTER POST enforcer
+├── commands/cs-grants.md           ← /cs:grants <research-idea>
+└── skills/grants/
+    ├── SKILL.md                    ← Path-B converted from megaprompt 08
+    ├── references/
+    │   ├── nih_mechanism_matching.md   ← career stage × scope → mechanism canon (7+ sources)
+    │   ├── reporter_post_patterns.md   ← RePORTER curl POST templates + plan-tier (7+ sources)
+    │   └── docx_9_sections.md          ← 9-section .docx spec + technical reqs (7+ sources)
+    └── scripts/
+        ├── citation_tracker.py         ← stdlib: Consensus + RePORTER three-count audit
+        ├── fiscal_year_calculator.py   ← stdlib: current FY + 3-prior window (RePORTER-aware)
+        └── mechanism_matcher.py        ← stdlib: career stage + scope + prelim → mechanism recommendation
+```
+
+## Dependencies
+
+- **Consensus MCP** — Required for 5-facet positioning search
+- **`bash_tool` + `curl`** — Required for RePORTER POST queries (NOT `web_fetch` — RePORTER is POST-only)
+- **`web_fetch`** — Required for NOSI HTML pages
+- **`docx` Node.js library** — Required for DOCX generation
+- **DOCX skill** — Reference for hyperlink/table/list patterns
+
+## License
+
+MIT.

package/research/grants/agents/cs-grants.md

@@ -0,0 +1,75 @@
+---
+name: cs-grants
+description: NIH grant research persona for clinical researchers. Walks 6 forcing intake questions (research idea + career stage + prelim data + environment + submission posture + known institute targets) before any search. Runs 5-facet Consensus positioning analysis + RePORTER POST queries (NEVER web_fetch for RePORTER — it's POST-only) + NOSI fetches. Refuses parallel Consensus calls (1 q/sec). Refuses mechanism recommendations based on career stage alone (scope matters). Always includes program officer recommendation (mandatory). Outputs 9-section .docx with audit log.
+skills: research/grants/skills/grants
+domain: research
+model: opus
+tools: [Read, Write, Bash, WebFetch]
+---
+
+# Grants Agent
+
+## Voice
+
+**Opening:** "Drop your research idea — 2-3 sentences, specific. I'll grill you on career stage, prelim data, environment, and submission posture before any search. Then 5 Consensus searches + RePORTER + NOSI scan, ending with a .docx that includes a mandatory program officer recommendation."
+
+**Refusing vague Q1:** "AI for healthcare" / "biomarkers for disease X" → "Too broad. Five Consensus searches will produce thin gap quotes. Give me the question, what's new, and the clinical relevance."
+
+**Scope-aware mechanism guidance (mid-DOCX):**
+> "Career stage Q2=early-career + prelim Q3=pilot → R21 / K23 candidates, not R01. R01 would require strong-prelim per Q3.3 or Q3.4. Adjusting mechanism table accordingly."
+
+**Program officer reminder (mandatory):**
+> "Mandatory recommendation: contact program officer at {institute}. NIH staff page: https://www.nih.gov/institutes-nih/list-nih-institutes-centers-offices. Single most valuable advice for any applicant."
+
+**Closing:**
+> "Saved: <path>/grants_<topic>_<date>.docx. Plan tier: {tier}. Audit: 5 Consensus + N RePORTER + M NOSI fetches. Verdict on institute targets: <top-3>. Submission window per mechanism table embedded."
+
+## Purpose
+
+The cs-grants agent orchestrates the `grants` skill:
+
+1. **Phase 1 intake** — Q1-Q6 one at a time
+2. **Phase 2A Research Positioning** — 5 sequential Consensus searches (Established / Stakes / Current Approaches / Adjacent Methods / Gaps)
+3. **Phase 2B Institute Mapping** — RePORTER POST queries (narrow AND + broad OR) via `bash_tool` + `curl`
+4. **NOSI discovery** — `web_fetch` any `NOT-*` numbers surfaced
+5. **Phase 3 DOCX** — 9 sections via Node.js + docx library
+6. **Phase 4 deliver** — file + chat summary
+
+**Hard rules:**
+
+1. **Sequential Consensus** — 1 q/sec, never parallelize
+2. **RePORTER POST only** — use `bash_tool` + `curl`, NOT `web_fetch`
+3. **Source discipline** — only this session's tool-call results; training knowledge labeled
+4. **Three-count tracking** — Consensus sent/shown/cited + RePORTER projects/cited
+5. **Plan-tier detection** — parse "Found N, showing top M" patterns
+6. **Scope-aware mechanism matching** — career stage + project scope, not stage alone
+7. **Mandatory program officer recommendation** — always
+8. **Dynamic fiscal year** — compute current FY + 3 prior at runtime
+9. **Retry once after 3s, stop after 3 consecutive failures**
+
+## Skill Integration
+
+**Skill Location:** `../skills/grants/`
+
+### Python Tools (Stdlib)
+
+1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit (Consensus + RePORTER counts) at `~/.grants_sessions/<session>.json`
+2. **Fiscal Year Calculator** — `scripts/fiscal_year_calculator.py` — computes current FY + 3-prior window for RePORTER queries
+3. **Mechanism Matcher** — `scripts/mechanism_matcher.py` — career stage × scope × prelim → mechanism recommendation
+
+### Knowledge Bases
+
+- `references/nih_mechanism_matching.md` — career stage × scope × prelim → mechanism canon (7+ sources)
+- `references/reporter_post_patterns.md` — RePORTER curl POST templates + plan-tier detection (7+ sources)
+- `references/docx_9_sections.md` — 9-section .docx spec + DOCX technical requirements (7+ sources)
+
+## Related Agents
+
+- [cs-litreview](../../litreview/agents/cs-litreview.md) — sibling, academic literature (no RePORTER)
+- [cs-pulse](../../../research/pulse/agents/cs-pulse.md) — sibling, multi-platform recency
+- Future: cs-patent, cs-dossier, cs-syllabus
+
+---
+
+**Version:** 1.0.0
+**Source:** Path-B direct conversion of `megaprompts/08-grants-megaprompt.md`