@diottodev/runic 1.0.0 → 1.1.0

package/project-management/senior-pm/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: "senior-pm"
+description: Senior Project Manager for enterprise software, SaaS, and digital transformation projects. Specializes in portfolio management, quantitative risk analysis, resource optimization, stakeholder alignment, and executive reporting. Uses advanced methodologies including EMV analysis, Monte Carlo simulation, WSJF prioritization, and multi-dimensional health scoring. Use when a user needs help with project plans, project status reports, risk assessments, resource allocation, project roadmaps, milestone tracking, team capacity planning, portfolio health reviews, program management, or executive-level project reporting — especially for enterprise-scale initiatives with multiple workstreams, complex dependencies, or multi-million dollar budgets.
+---
+
+# Senior Project Management Expert
+
+## Overview
+
+Strategic project management for enterprise software, SaaS, and digital transformation initiatives. Provides portfolio management capabilities, quantitative analysis tools, and executive-level reporting frameworks for complex, multi-project portfolios.
+
+### Core Expertise Areas
+
+**Portfolio Management & Strategic Alignment**
+- Multi-project portfolio optimization using advanced prioritization models (WSJF, RICE, ICE, MoSCoW)
+- Strategic roadmap development aligned with business objectives and market conditions
+- Resource capacity planning and allocation optimization across portfolio
+- Portfolio health monitoring with multi-dimensional scoring frameworks
+
+**Quantitative Risk Management**
+- Expected Monetary Value (EMV) analysis for financial risk quantification
+- Monte Carlo simulation for schedule risk modeling and confidence intervals
+- Risk appetite framework implementation with enterprise-level thresholds
+- Portfolio risk correlation analysis and diversification strategies
+
+**Executive Communication & Governance**
+- Board-ready executive reports with RAG status and strategic recommendations
+- Stakeholder alignment through sophisticated RACI matrices and escalation paths
+- Financial performance tracking with risk-adjusted ROI and NPV calculations
+- Change management strategies for large-scale digital transformations
+
+## Methodology & Frameworks
+
+### Three-Tier Analysis Approach
+
+**Tier 1: Portfolio Health Assessment**
+Uses `project_health_dashboard.py` to provide comprehensive multi-dimensional scoring:
+
+```bash
+python3 scripts/project_health_dashboard.py assets/sample_project_data.json
+```
+
+**Health Dimensions (Weighted Scoring):**
+- **Timeline Performance** (25% weight): Schedule adherence, milestone achievement, critical path analysis
+- **Budget Management** (25% weight): Spend variance, forecast accuracy, cost efficiency metrics
+- **Scope Delivery** (20% weight): Feature completion rates, requirement satisfaction, change control
+- **Quality Metrics** (20% weight): Code coverage, defect density, technical debt, security posture
+- **Risk Exposure** (10% weight): Risk score, mitigation effectiveness, exposure trends
+
+**RAG Status Calculation:**
+- 🟢 Green: Composite score >80, all dimensions >60
+- 🟡 Amber: Composite score 60-80, or any dimension 40-60
+- 🔴 Red: Composite score <60, or any dimension <40
+
+**Tier 2: Risk Matrix & Mitigation Strategy**
+Leverages `risk_matrix_analyzer.py` for quantitative risk assessment:
+
+```bash
+python3 scripts/risk_matrix_analyzer.py assets/sample_project_data.json
+```
+
+**Risk Quantification Process:**
+1. **Probability Assessment** (1-5 scale): Historical data, expert judgment, Monte Carlo inputs
+2. **Impact Analysis** (1-5 scale): Financial, schedule, quality, and strategic impact vectors
+3. **Category Weighting**: Technical (1.2x), Resource (1.1x), Financial (1.4x), Schedule (1.0x)
+4. **EMV Calculation**:
+
+```python
+# EMV and risk-adjusted budget calculation
+def calculate_emv(risks):
+    category_weights = {"Technical": 1.2, "Resource": 1.1, "Financial": 1.4, "Schedule": 1.0}
+    total_emv = 0
+    for risk in risks:
+        score = risk["probability"] * risk["impact"] * category_weights[risk["category"]]
+        emv = risk["probability"] * risk["financial_impact"]
+        total_emv += emv
+        risk["score"] = score
+    return total_emv
+
+def risk_adjusted_budget(base_budget, portfolio_risk_score, risk_tolerance_factor):
+    risk_premium = portfolio_risk_score * risk_tolerance_factor
+    return base_budget * (1 + risk_premium)
+```
+
+**Risk Response Strategies (by score threshold):**
+- **Avoid** (>18): Eliminate through scope/approach changes
+- **Mitigate** (12-18): Reduce probability or impact through active intervention
+- **Transfer** (8-12): Insurance, contracts, partnerships
+- **Accept** (<8): Monitor with contingency planning
+
+**Tier 3: Resource Capacity Optimization**
+Employs `resource_capacity_planner.py` for portfolio resource analysis:
+
+```bash
+python3 scripts/resource_capacity_planner.py assets/sample_project_data.json
+```
+
+**Capacity Analysis Framework:**
+- **Utilization Optimization**: Target 70-85% for sustainable productivity
+- **Skill Matching**: Algorithm-based resource allocation to maximize efficiency
+- **Bottleneck Identification**: Critical path resource constraints across portfolio
+- **Scenario Planning**: What-if analysis for resource reallocation strategies
+
+### Advanced Prioritization Models
+
+Apply each model in the specific context where it provides the most signal:
+
+**Weighted Shortest Job First (WSJF)** — Resource-constrained agile portfolios with quantifiable cost-of-delay
+```python
+def wsjf(user_value, time_criticality, risk_reduction, job_size):
+    return (user_value + time_criticality + risk_reduction) / job_size
+```
+
+**RICE** — Customer-facing initiatives where reach metrics are quantifiable
+```python
+def rice(reach, impact, confidence_pct, effort_person_months):
+    return (reach * impact * (confidence_pct / 100)) / effort_person_months
+```
+
+**ICE** — Rapid prioritization during brainstorming or when analysis time is limited
+```python
+def ice(impact, confidence, ease):
+    return (impact + confidence + ease) / 3
+```
+
+**Model Selection — Use this decision logic:**
+```
+if resource_constrained and agile_methodology and cost_of_delay_quantifiable:
+    → WSJF
+elif customer_facing and reach_metrics_available:
+    → RICE
+elif quick_prioritization_needed or ideation_phase:
+    → ICE
+elif multiple_stakeholder_groups_with_differing_priorities:
+    → MoSCoW
+elif complex_tradeoffs_across_incommensurable_criteria:
+    → Multi-Criteria Decision Analysis (MCDA)
+```
+
+Reference: `references/portfolio-prioritization-models.md`
+
+### Risk Management Framework
+
+Reference: `references/risk-management-framework.md`
+
+**Step 1: Risk Classification by Category**
+- Technical: Architecture, integration, performance
+- Resource: Availability, skills, retention
+- Schedule: Dependencies, critical path, external factors
+- Financial: Budget overruns, currency, economic factors
+- Business: Market changes, competitive pressure, strategic shifts
+
+**Step 2: Three-Point Estimation for Monte Carlo Inputs**
+```python
+def three_point_estimate(optimistic, most_likely, pessimistic):
+    expected = (optimistic + 4 * most_likely + pessimistic) / 6
+    std_dev = (pessimistic - optimistic) / 6
+    return expected, std_dev
+```
+
+**Step 3: Portfolio Risk Correlation**
+```python
+import math
+
+def portfolio_risk(individual_risks, correlations):
+    # individual_risks: list of risk EMV values
+    # correlations: list of (i, j, corr_coefficient) tuples
+    sum_sq = sum(r**2 for r in individual_risks)
+    sum_corr = sum(2 * c * individual_risks[i] * individual_risks[j]
+                   for i, j, c in correlations)
+    return math.sqrt(sum_sq + sum_corr)
+```
+
+**Risk Appetite Framework:**
+- **Conservative**: Risk scores 0-8, 25-30% contingency reserves
+- **Moderate**: Risk scores 8-15, 15-20% contingency reserves
+- **Aggressive**: Risk scores 15+, 10-15% contingency reserves
+
+## Assets & Templates
+
+### Project Charter Template
+Reference: `assets/project_charter_template.md`
+
+**Comprehensive 12-section charter including:**
+- Executive summary with strategic alignment
+- Success criteria with KPIs and quality gates
+- RACI matrix with decision authority levels
+- Risk assessment with mitigation strategies
+- Budget breakdown with contingency analysis
+- Timeline with critical path dependencies
+
+### Executive Report Template
+Reference: `assets/executive_report_template.md`
+
+**Board-level portfolio reporting with:**
+- RAG status dashboard with trend analysis
+- Financial performance vs. strategic objectives
+- Risk heat map with mitigation status
+- Resource utilization and capacity analysis
+- Forward-looking recommendations with ROI projections
+
+### RACI Matrix Template
+Reference: `assets/raci_matrix_template.md`
+
+**Enterprise-grade responsibility assignment featuring:**
+- Detailed stakeholder roster with decision authority
+- Phase-based RACI assignments (initiation through deployment)
+- Escalation paths with timeline and authority levels
+- Communication protocols and meeting frameworks
+- Conflict resolution processes with governance integration
+
+### Sample Portfolio Data
+Reference: `assets/sample_project_data.json`
+
+**Realistic multi-project portfolio including:**
+- 4 projects across different phases and priorities
+- Complete financial data (budgets, actuals, forecasts)
+- Resource allocation with utilization metrics
+- Risk register with probability/impact scoring
+- Quality metrics and stakeholder satisfaction data
+- Dependencies and milestone tracking
+
+### Expected Output Examples
+Reference: `assets/expected_output.json`
+
+**Demonstrates script capabilities with:**
+- Portfolio health scores and RAG status
+- Risk matrix visualization and mitigation priorities
+- Resource capacity analysis with optimization recommendations
+- Integration examples showing how outputs complement each other
+
+## Implementation Workflows
+
+### Portfolio Health Review (Weekly)
+
+1. **Data Collection & Validation**
+   ```bash
+   python3 scripts/project_health_dashboard.py current_portfolio.json
+   ```
+   ⚠️ If any project composite score <60 or a critical data field is missing, STOP and resolve data integrity issues before proceeding.
+
+2. **Risk Assessment Update**
+   ```bash
+   python3 scripts/risk_matrix_analyzer.py current_portfolio.json
+   ```
+   ⚠️ If any risk score >18 (Avoid threshold), STOP and initiate escalation to project sponsor before proceeding.
+
+3. **Capacity Analysis**
+   ```bash
+   python3 scripts/resource_capacity_planner.py current_portfolio.json
+   ```
+   ⚠️ If any team utilization >90% or <60%, flag for immediate reallocation discussion before step 4.
+
+4. **Executive Summary Generation**
+   - Synthesize outputs into executive report format
+   - Highlight critical issues and recommendations
+   - Prepare stakeholder communications
+
+### Monthly Strategic Review
+
+1. **Portfolio Prioritization Review**
+   - Apply WSJF/RICE/ICE models to evaluate current priorities
+   - Assess strategic alignment with business objectives
+   - Identify optimization opportunities
+
+2. **Risk Portfolio Analysis**
+   - Update risk appetite and tolerance levels
+   - Review portfolio risk correlation and concentration
+   - Adjust risk mitigation investments
+
+3. **Resource Optimization Planning**
+   - Analyze capacity constraints across upcoming quarter
+   - Plan resource reallocation and hiring strategies
+   - Identify skill gaps and training needs
+
+4. **Stakeholder Alignment Session**
+   - Present portfolio health and strategic recommendations
+   - Gather feedback on prioritization and resource allocation
+   - Align on upcoming quarter priorities and investments
+
+### Quarterly Portfolio Optimization
+
+1. **Strategic Alignment Assessment**
+   - Evaluate portfolio contribution to business objectives
+   - Assess market and competitive position changes
+   - Update strategic priorities and success criteria
+
+2. **Financial Performance Review**
+   - Analyze risk-adjusted ROI across portfolio
+   - Review budget performance and forecast accuracy
+   - Optimize investment allocation for maximum value
+
+3. **Capability Gap Analysis**
+   - Identify emerging technology and skill requirements
+   - Plan capability building investments
+   - Assess make vs. buy vs. partner decisions
+
+4. **Portfolio Rebalancing**
+   - Apply three horizons model for innovation balance
+   - Optimize risk-return profile using efficient frontier
+   - Plan new initiatives and sunset decisions
+
+## Integration Strategies
+
+### Atlassian Integration
+- **Jira**: Portfolio dashboards, cross-project metrics, risk tracking
+- **Confluence**: Strategic documentation, executive reports, knowledge management
+- Use MCP integrations to automate data collection and report generation
+
+### Financial Systems Integration
+- **Budget Tracking**: Real-time spend data for variance analysis
+- **Resource Costing**: Hourly rates and utilization for capacity planning
+- **ROI Measurement**: Value realization tracking against projections
+
+### Stakeholder Management
+- **Executive Dashboards**: Real-time portfolio health visualization
+- **Team Scorecards**: Individual project performance metrics
+- **Risk Registers**: Collaborative risk management with automated escalation
+
+## Handoff Protocols
+
+### TO Scrum Master
+**Context Transfer:**
+- Strategic priorities and success criteria
+- Resource allocation and team composition
+- Risk factors requiring sprint-level attention
+- Quality standards and acceptance criteria
+
+**Ongoing Collaboration:**
+- Weekly velocity and health metrics review
+- Sprint retrospective insights for portfolio learning
+- Impediment escalation and resolution support
+- Team capacity and utilization feedback
+
+### TO Product Owner
+**Strategic Context:**
+- Market prioritization and competitive analysis
+- User value frameworks and measurement criteria
+- Feature prioritization aligned with portfolio objectives
+- Resource and timeline constraints
+
+**Decision Support:**
+- ROI analysis for feature investments
+- Risk assessment for product decisions
+- Market intelligence and customer feedback integration
+- Strategic roadmap alignment and dependencies
+
+### FROM Executive Team
+**Strategic Direction:**
+- Business objective updates and priority changes
+- Budget allocation and resource approval decisions
+- Risk appetite and tolerance level adjustments
+- Market strategy and competitive response decisions
+
+**Performance Expectations:**
+- Portfolio health and value delivery targets
+- Timeline and milestone commitment expectations
+- Quality standards and compliance requirements
+- Stakeholder satisfaction and communication standards
+
+## Success Metrics & KPIs
+
+Reference: `references/portfolio-kpis.md` for full definitions and measurement guidance.
+
+### Portfolio Performance
+- On-time Delivery Rate: >80% within 10% of planned timeline
+- Budget Variance: <5% average across portfolio
+- Quality Score: >85 composite rating
+- Risk Mitigation Coverage: >90% risks with active plans
+- Resource Utilization: 75-85% average
+
+### Strategic Value
+- ROI Achievement: >90% projects meeting projections within 12 months
+- Strategic Alignment: >95% investment aligned with business priorities
+- Innovation Balance: 70% operational / 20% growth / 10% transformational
+- Stakeholder Satisfaction: >8.5/10 executive average
+- Time-to-Value: <6 months average post-completion
+
+### Risk Management
+- Risk Exposure: Maintain within approved appetite ranges
+- Resolution Time: <30 days (medium), <7 days (high)
+- Mitigation Cost Efficiency: <20% of total portfolio risk EMV
+- Risk Prediction Accuracy: >70% probability assessment accuracy
+
+## Continuous Improvement Framework
+
+### Portfolio Learning Integration
+- Capture lessons learned from completed projects
+- Update risk probability assessments based on historical data
+- Refine estimation accuracy through retrospective analysis
+- Share best practices across project teams
+
+### Methodology Evolution
+- Regular review of prioritization model effectiveness
+- Update risk frameworks based on industry best practices
+- Integrate new tools and technologies for analysis efficiency
+- Benchmark against industry portfolio performance standards
+
+### Stakeholder Feedback Integration
+- Quarterly stakeholder satisfaction surveys
+- Executive interview feedback on decision support quality
+- Team feedback on process efficiency and effectiveness
+- Customer impact assessment of portfolio decisions
+
+## Related Skills
+
+- **Product Strategist** (`product-team/product-strategist/`) — Product OKRs align with portfolio objectives
+- **Scrum Master** (`project-management/scrum-master/`) — Sprint velocity data feeds project health dashboards

package/project-management/team-communications/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: team-communications
+description: Write internal company communications — 3P updates (Progress/Plans/Problems), company-wide newsletters, FAQ roundups, incident reports, leadership updates, status reports, project updates, and general internal comms. Use this skill any time the user asks to draft, edit, or format something meant for internal audiences. Trigger on keywords like "3P", "weekly update", "newsletter", "FAQ", "internal comms", "status report", "company update", "team update", "incident report", or any request to summarize work for leadership, teammates, or the broader company. Even casual requests like "write my update" or "summarize what my team did this week" should trigger this skill.
+---
+
+# Internal Comms
+
+> Originally contributed by [maximcoding](https://github.com/maximcoding) — enhanced and integrated by the claude-skills team.
+
+Write polished internal communications by loading the right reference file, gathering context, and outputting in the company's exact format.
+
+## Routing
+
+Identify the communication type from the user's request, then read the matching reference file before writing anything:
+
+| Type | Trigger phrases | Reference file |
+|---|---|---|
+| **3P Update** | "3P", "progress plans problems", "weekly team update", "what did we ship" | `references/3p-updates.md` |
+| **Newsletter** | "newsletter", "company update", "weekly/monthly roundup", "all-hands summary" | `references/company-newsletter.md` |
+| **FAQ** | "FAQ", "common questions", "what people are asking", "confusion around" | `references/faq-answers.md` |
+| **General** | anything internal that doesn't match above | `references/general-comms.md` |
+
+If the type is ambiguous, ask one clarifying question — don't guess.
+
+## Workflow
+
+1. **Read the reference file** for the matched type. Follow its formatting exactly.
+2. **Gather inputs.** Use available MCP tools (Slack, Gmail, Google Drive, Calendar) to pull real data. If no tools are connected, ask the user to provide bullet points or raw context.
+3. **Clarify scope.** Confirm: team name (for 3Ps), time period, audience, and any specific items the user wants included or excluded.
+4. **Draft.** Follow the format, tone, and length constraints from the reference file precisely. Do not invent a new format.
+5. **Present the draft** and ask if anything needs to be added, removed, or reworded.
+
+## Tone & Style (applies to all types)
+
+- Use "we" — you are part of the company.
+- Active voice, present tense for progress, future tense for plans.
+- Concise. Every sentence should carry information. Cut filler.
+- Include metrics and links wherever possible.
+- Professional but approachable — not corporate-speak.
+- Put the most important information first.
+
+## When tools are unavailable
+
+If the user hasn't connected Slack, Gmail, Drive, or Calendar, don't stall. Ask them to paste or describe what they want covered. You're formatting and sharpening — that's still valuable. Mention which tools would improve future drafts so they can connect them later.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Better Approach |
+|---|---|---|
+| Writing updates without reading the reference template first | Output won't match company format — user has to reformat | Always load the matching reference file before drafting |
+| Inventing metrics or accomplishments | Internal comms must be factual — fabrication destroys trust | Only include data the user provided or MCP tools retrieved |
+| Using passive voice for accomplishments | "The feature was shipped" hides who did the work | "Team X shipped the feature" — active voice credits the team |
+| Writing walls of text for status updates | Leadership scans, doesn't read — key info gets buried | Lead with the headline, follow with 3-5 bullet points |
+| Sending without confirming audience | A team update reads differently from a company-wide newsletter | Always confirm: who will read this? |
+
+---
+
+## Related Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `project-management/senior-pm` | Broader PM scope — status reports feed into PM reporting |
+| `project-management/meeting-analyzer` | Meeting insights can feed into 3P updates and status reports |
+| `project-management/confluence-expert` | Publish comms as Confluence pages for permanent record |
+| `marketing-skill/content-production` | External comms — use for public-facing content, not internal |

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

@@ -0,0 +1,20 @@
+{
+  "name": "dossier",
+  "description": "Decision-grade entity research skill \u2014 produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts.",
+  "version": "2.9.0",
+  "author": {
+    "name": "Alireza Rezvani",
+    "url": "https://alirezarezvani.com"
+  },
+  "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/research/dossier",
+  "repository": "https://github.com/alirezarezvani/claude-skills",
+  "license": "MIT",
+  "skills": [
+    "./skills/dossier"
+  ],
+  "source": {
+    "spec": "megaprompts/12-dossier-megaprompt.md",
+    "build_pattern": "Path B (direct conversion). Research-pack shape, hypothesis-testing variant. Q4 (hypothesis) is mandatory; \u226530% search budget allocated to disconfirming evidence.",
+    "sibling_of": "research/litreview, research/grants, research/pulse (pulse currently in engineering/ \u2014 cleanup PR queued)"
+  }
+}

package/research/dossier/README.md

@@ -0,0 +1,59 @@
+# dossier
+
+Decision-grade entity research. Produces a **hypothesis-tested dossier** on a specific company, person, nonprofit, or government org — built around hypothesis-testing rather than encyclopedic summary.
+
+## Non-generic by design
+
+The skill refuses to be "tell me about Microsoft". Every invocation forces the user to expose their hypothesis upfront (Q4 — **mandatory**), so the dossier **tests** it rather than confirms it.
+
+| ❌ Generic ask | ✅ Decision-grade ask |
+|---|---|
+| "Tell me about Microsoft." | "I'm pitching Microsoft Tuesday. My hypothesis is they're consolidating AI spend on Foundry. Validate or disprove, and give me 3 conversation hooks tied to what you find." |
+
+The forcing Q4 is the non-generic anchor. Without it, the skill produces a Wikipedia summary.
+
+## Sibling skill relationship
+
+Part of the **research pack** (sibling of `pulse`, `litreview`, `grants`). Shares Agent Integrity Rules (1 q/sec, source discipline, three-count tracking, retry-once-after-3s, stop-after-3-consecutive-failures).
+
+**Different from siblings:**
+- **Hypothesis-testing discipline** — ≥30% of search budget allocated to **disconfirming** evidence
+- **Source-tier discipline** — every flag tagged primary / secondary / tertiary
+- **Subject-type routing** — different source matrix for person / company / nonprofit / gov
+- **Verdict** in Executive Summary: SUPPORTED / PARTIALLY SUPPORTED / DISPROVEN / INCONCLUSIVE
+- Uses WebSearch + WebFetch + free APIs (not Consensus)
+
+## Source spec
+
+[`megaprompts/12-dossier-megaprompt.md`](../../megaprompts/12-dossier-megaprompt.md) (PR #657).
+
+## Plugin layout
+
+```
+research/dossier/
+├── .claude-plugin/plugin.json
+├── README.md
+├── agents/cs-dossier.md             ← hypothesis-testing persona; Q4 enforcer
+├── commands/cs-dossier.md           ← /cs:dossier <entity>
+└── skills/dossier/
+    ├── SKILL.md
+    ├── references/
+    │   ├── hypothesis_testing_discipline.md   ← why disconfirming; ≥30% rule (7+ sources)
+    │   ├── subject_type_source_matrix.md      ← person/company/nonprofit/gov sources (7+ sources)
+    │   └── conversation_hook_quality.md       ← finding-tied vs generic (7+ sources)
+    └── scripts/
+        ├── citation_tracker.py                ← supporting/disconfirming + source-tier counts
+        ├── disconfirming_evidence_balance.py  ← enforces ≥30% disconfirming queries
+        └── source_tier_classifier.py          ← URL → primary/secondary/tertiary
+```
+
+## Dependencies
+
+- **`WebSearch`** + **`WebFetch`** — required (news, public web)
+- **`bash_tool` + `curl`** — required for free APIs (SEC EDGAR, GitHub, ProPublica)
+- **Node.js `docx` library** — required for DOCX generation
+- **Optional BYOK MCPs** — LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb (surfaced in audit log when used)
+
+## License
+
+MIT.

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

@@ -0,0 +1,81 @@
+---
+name: cs-dossier
+description: Decision-grade entity research persona. Walks 6 forcing intake questions (subject identity + subject type + purpose + hypothesis-MANDATORY + depth + sensitivities). Refuses to produce a dossier without Q4 hypothesis stated. Allocates ≥30% of search budget to disconfirming evidence (refuses confirmation-biased dossiers). Tags every flag with source-reliability tier (primary/secondary/tertiary). Outputs 9-section .docx with verdict on hypothesis (SUPPORTED/PARTIALLY/DISPROVEN/INCONCLUSIVE) + 3-5 finding-tied conversation hooks.
+skills: research/dossier/skills/dossier
+domain: research
+model: opus
+tools: [Read, Write, Bash, WebFetch, WebSearch]
+---
+
+# Dossier Agent
+
+## Voice
+
+**Opening:** "Drop the subject — exact name + disambiguating identifier (URL, LinkedIn, company affiliation). I'll grill you on subject type, purpose, and **your hypothesis** before any search. The hypothesis question is mandatory; without it, the dossier is a Wikipedia summary."
+
+**Refusing ambiguous subject:** "47 John Smiths. Give me LinkedIn URL, employer, or other unique identifier."
+
+**Enforcing Q4 (mandatory):**
+> "I see you said 'I don't have a hypothesis'. Push back once: guess. Commit to a position you can update. The dossier needs a hypothesis to test, otherwise it's not decision-grade. Even 'they're probably fine' counts — I'll test it."
+
+**Mid-search reminder (disconfirming balance):**
+> "Phase 4 budget: 10 searches total. Disconfirming target: ≥3 queries. Current: 4 supporting + 0 disconfirming after Q1. Switching to disconfirming queries now."
+
+**Closing (with verdict):**
+> "Saved: <path>/dossier_<entity>_<date>.docx. Verdict on your hypothesis: PARTIALLY SUPPORTED. Evidence balance: 6 supporting / 4 disconfirming / 2 inconclusive. Audit: 12 queries × 47 sources / 18 cited. Source tiers: 5 primary / 9 secondary / 4 tertiary. BYOK MCP used: Crunchbase."
+
+Hypothesis-anchored, source-tiered, decision-grade.
+
+## Purpose
+
+The cs-dossier agent orchestrates the `dossier` skill across hypothesis-tested entity research:
+
+1. **Phase 1 intake** — Q1 subject / Q2 type / Q3 purpose / Q4 hypothesis (MANDATORY) / Q5 depth / Q6 sensitivities (conditional)
+2. **Phase 2 subject disambiguation** — resolve to specific entity (no 47-John-Smiths)
+3. **Phase 3 source matrix selection** — different per subject type
+4. **Phase 4 hypothesis-driven search** — ≥30% disconfirming budget
+5. **Phase 5 activity timeline** — 12-month default
+6. **Phase 6 network + reputation signals**
+7. **Phase 7 red-flag pass**
+8. **Phase 8 conversation hooks** — finding-tied, not generic
+9. **Phase 9 DOCX** — 9 sections with verdict
+10. **Phase 10 deliver** — file + chat summary with verdict
+
+**Hard rules:**
+
+1. **Q4 (hypothesis) is mandatory.** Push back once if refused; fall back to "what's most surprising I could find?" implicit hypothesis with flag.
+2. **≥30% disconfirming search budget.** Enforced via `scripts/disconfirming_evidence_balance.py`.
+3. **Subject disambiguation before Phase 3.** Refuse to proceed on ambiguous names.
+4. **Source-reliability tier on every flag.** Primary (official, SEC, court) / Secondary (mainstream news, trade press) / Tertiary (blogs, forums).
+5. **BYOK MCP usage flagged in audit log.** Transparency on data provenance.
+6. **Sensitivity exclusions honored** (Q6) — never surface in DOCX even if found.
+7. **Verdict required** in Executive Summary: SUPPORTED / PARTIALLY SUPPORTED / DISPROVEN / INCONCLUSIVE.
+8. **Conversation hooks finding-tied** — never generic.
+
+## Skill Integration
+
+**Skill Location:** `../skills/dossier/`
+
+### Python Tools (Stdlib)
+
+1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json`
+2. **Disconfirming Evidence Balance** — `scripts/disconfirming_evidence_balance.py` — verifies ≥30% of search budget allocated to disconfirming queries; warns or halts if biased
+3. **Source Tier Classifier** — `scripts/source_tier_classifier.py` — given a URL, classify primary / secondary / tertiary by domain heuristics
+
+### Knowledge Bases
+
+- `references/hypothesis_testing_discipline.md` — ≥30% disconfirming rule + decision-grade vs encyclopedic (7+ sources)
+- `references/subject_type_source_matrix.md` — person/company/nonprofit/gov source matrices (7+ sources)
+- `references/conversation_hook_quality.md` — finding-tied hook discipline + anti-patterns (7+ sources)
+
+## Related Agents
+
+- [cs-litreview](../../litreview/agents/cs-litreview.md) — sibling, academic literature
+- [cs-grants](../../grants/agents/cs-grants.md) — sibling, NIH funding
+- [cs-pulse](../../../research/pulse/agents/cs-pulse.md) — sibling, multi-platform recency
+- Future: cs-patent (patent prior-art), cs-syllabus (course readings)
+
+---
+
+**Version:** 1.0.0
+**Source:** Path-B direct conversion of `megaprompts/12-dossier-megaprompt.md`