---
slug: "sigint"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/zircote/sigint@main/README.md"
repo: "https://github.com/zircote/sigint"
source_file: "README.md"
branch: "main"
---
# sigint - Signal Intelligence

[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-06b6d4?style=flat-square&logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code)
[![License: MIT](https://img.shields.io/badge/License-MIT-8b5cf6?style=flat-square)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.10.3-22c55e?style=flat-square)](CHANGELOG.md)

Comprehensive market research toolkit for Claude Code with report generation, GitHub issue creation, and trend-based analysis.

<p align="center">
  <img src=".github/readme-infographic.svg" alt="sigint workflow" width="800">
</p>

## Quick Start

```bash
# 1. Start research with a topic
/sigint:start AI-powered code review tools

# 2. Answer elicitation questions (decision context, audience, priorities)

# 3. Check progress
/sigint:status

# 4. Generate report
/sigint:report

# 5. Create GitHub issues (optional)
/sigint:issues
```

See the [Getting Started Tutorial](https://github.com/zircote/sigint/blob/HEAD/docs/tutorials/getting-started.md) for a detailed walkthrough.

## Features

- **Swarm-Orchestrated Research**: Parallel dimension-analysts coordinate via task system and file-based state
- **Iterative Research Workflow**: Start, refine, and finalize market research through commands
- **Multi-Audience Reports**: Generate reports for executives, PMs, investors, and developers
- **Trend-Based Modeling**: Three-valued logic analysis (INC/DEC/CONST) for uncertain data
- **GitHub Integration**: Automatically create sprint-sized issues from findings
- **RLM Large Document Processing**: Source-chunker handles documents exceeding context limits
- **Multi-Format Output**: Markdown, HTML, Mermaid diagrams

## Installation

### Claude Code

```bash
# Option 1: Plugin Marketplace (recommended)
/plugins add sigint

# Option 2: Local development
claude --plugin-dir /path/to/sigint

# Option 3: Manual install to plugins directory
cp -r sigint ~/.claude/plugins/
```

### Cowork

1. Open Claude Desktop app > **Cowork** tab
2. Click **Customize** > **Browse plugins**
3. Search for "sigint" and click **Install**

For organization-wide deployment and detailed setup, see the [Cowork deployment guide](https://github.com/zircote/sigint/blob/HEAD/docs/how-to/deploy-to-cowork.md).

## Commands

| Command | Description |
|---------|-------------|
| `/sigint:start <topic>` | Begin new research session |
| `/sigint:augment <area>` | Deep-dive into specific area |
| `/sigint:update` | Refresh existing research data |
| `/sigint:report` | Generate comprehensive report |
| `/sigint:falsify` | Adversarially falsify findings (web-only disconfirming search) and remediate (quarantine, downgrade, queue followups) |
| `/sigint:issues` | Create GitHub issues from findings |
| `/sigint:resume` | Resume previous research session |
| `/sigint:status` | Show current research state |
| `/sigint:init` | Initialize plugin configuration |

## Agents

- **research-orchestrator**: Coordinates parallel dimension-analysts, merges findings
- **dimension-analyst**: Focused research on a single dimension (competitive, sizing, trends, etc.)
- **source-chunker**: RLM processor for large documents — partitions, analyzes chunks, synthesizes
- **issue-architect**: Converts findings to sprint-sized GitHub issues
- **report-synthesizer**: Generates multi-format reports with visualizations
- **falsification-analyst**: Adversarially attempts to disconfirm findings via web-only search; assigns ordinal verdicts (`falsified`/`weakened`/`survived`/`inconclusive`)

## Skills (Research Methodologies)

Each skill teaches AND executes the methodology:

1. **Competitive Analysis**: Porter's 5 Forces, competitor mapping
2. **Market Sizing**: TAM/SAM/SOM calculations
3. **Trend Analysis**: Macro/micro trend identification
4. **Customer Research**: Persona development, needs analysis
5. **Tech Assessment**: Technology evaluation, feasibility
6. **Financial Analysis**: Revenue models, unit economics
7. **Regulatory Review**: Compliance, legal considerations
8. **Report Writing**: Executive report best practices
9. **Trend Modeling**: Three-valued logic (INC/DEC/CONST), scenario graphs

## Report Structure

Reports include:
- Executive Summary
- Market Size (TAM/SAM/SOM)
- Competitive Landscape
- SWOT Analysis
- Recommendations
- Risk Assessment
- Data Sources & Methodology
- Transitional Scenario Graphs (Mermaid)

## Storage Structure

```
./reports/
├── README.md                   # Master index of all research
└── topic-name/
    ├── README.md               # Topic research index
    ├── state.json
    ├── YYYY-MM-DD-research.md
    ├── YYYY-MM-DD-report.md
    ├── YYYY-MM-DD-report.html
    ├── YYYY-MM-DD-falsification-report.md
    ├── YYYY-MM-DD-falsification-report.json
    ├── YYYY-MM-DD-falsification-followups.json
    └── YYYY-MM-DD-issues.json
```

## Adversarial Falsification

`sigint:falsify` treats every finding as a hypothesis under test. It generates disconfirming queries via a hybrid template + LLM-counter-hypothesis strategy, executes web-only adversarial search (no internal memory, no prior findings as evidence), and assigns one of four ordinal verdicts per atomic claim:

| Verdict | Remediation |
|---------|-------------|
| `falsified` | Move finding to `quarantine.json` with `gate: "post-falsification"`; queue retraction issue |
| `weakened` | Downgrade confidence one level; narrow summary; append disconfirming source; queue follow-up comment on existing issue |
| `survived` | Annotate `provenance.falsification_attempts`; optional confidence upgrade if multiple credible non-disconfirming sources |
| `inconclusive` | Annotate only |

The skill runs as **Phase 3.6** inside the research-orchestrator pipeline (between post-merge codex review and progress rendering) when invoked via `/sigint:start` or `/sigint:update`. It can also run standalone:

```bash
/sigint:falsify                                 # block-mode, all findings
/sigint:falsify --scope dimension:competitive   # one dimension
/sigint:falsify --scope finding:f_competitive_3 # one finding
/sigint:falsify --mode advisory                 # annotate without halting
/sigint:falsify --query-budget 4 --claim-budget 30
```

**Bounded epistemics**: a `survived` verdict is not proof of truth — it means N adversarial queries per claim were executed without finding disconfirming evidence. The falsification report always includes the actual search budget used so readers can judge how exhaustive the attempt was.

**One-round rule**: findings that already carry `provenance.falsification_attempts` from the current session are skipped (no recursive falsification).

## Configuration

Configuration uses `sigint.config.json` (schema v2.0) with project settings overriding global defaults.

### Configuration Locations

| Location | Scope | Purpose |
|----------|-------|---------|
| `./sigint.config.json` | Project | Project-specific configuration |
| `~/.claude/sigint.config.json` | Global | User-wide defaults for all projects |

**Resolution order**: Project > Global > Built-in defaults

### Configuration File Format

Create `sigint.config.json` at the project root (generated automatically by `/sigint:init`):

```json
{
  "version": "2.0",
  "defaults": {
    "default_repo": "owner/repo",
    "report_format": "markdown",
    "audiences": ["executives", "product-managers"]
  },
  "research": {
    "maxDimensions": 5,
    "dimensionTimeout": 300,
    "defaultPriorities": ["competitive", "sizing", "trends"]
  },
  "topics": {}
}
```

> **Migrating from legacy config?** If you have a `sigint.local.md` or `.sigint.config.json` v1.0, run `/sigint:migrate` to convert.

## Dependencies

**Required:**
- WebSearch/WebFetch tools for research

**Optional:**
- GitHub MCP server or GitHub CLI (`gh`) for issue creation

## References

### Primary Research

This plugin's trend modeling methodology is based on:

> Bočková, N., Volná, B., & Dohnal, M. (2025). "Optimisation of complex product innovation processes based on trend models with three-valued logic." *arXiv:2601.10768v1*. https://arxiv.org/abs/2601.10768

Key concepts adapted from this research:
- **Three-valued logic (INC/DEC/CONST)**: Minimally information-intensive quantifiers for trend analysis
- **Transitional scenario graphs**: Visual representation of possible state transitions
- **Qualitative modeling**: Analysis under information scarcity without precise numerical parameters

### Frameworks & Methodologies

- **Porter's Five Forces**: Porter, M.E. (1979). "How Competitive Forces Shape Strategy." *Harvard Business Review*, 57(2), 137-145.
- **SWOT Analysis**: Learned, E.P., Christensen, C.R., Andrews, K.R., & Guth, W.D. (1965). *Business Policy: Text and Cases*. Homewood, IL: Irwin.
- **TAM/SAM/SOM**: Blank, S. & Dorf, B. (2012). *The Startup Owner's Manual*. K&S Ranch.

### Market Research Methods

- **Competitive Analysis**: Fleisher, C.S. & Bensoussan, B.E. (2015). *Business and Competitive Analysis: Effective Application of New and Classic Methods*. FT Press.
- **Customer Research & Personas**: Cooper, A. (1999). *The Inmates Are Running the Asylum*. Sams Publishing.
- **Technology Assessment**: Coates, J.F. (1976). "Technology Assessment." *American Scientist*, 59(4), 412-418.

### Trend Modeling

- **Three-Valued Logic Foundations**: Kleene, S.C. (1952). *Introduction to Metamathematics*. North-Holland.
- **Scenario Planning**: Schwartz, P. (1991). *The Art of the Long View*. Doubleday.

### Financial Analysis

- **Unit Economics**: Ries, E. (2011). *The Lean Startup*. Crown Business.
- **Revenue Modeling**: Osterwalder, A. & Pigneur, Y. (2010). *Business Model Generation*. Wiley.

## License

MIT