Nw ResearchSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nw-research
description: "Gathers knowledge from web and files, cross-references across multiple sources, and produces cited research documents. Use when investigating technologies, patterns, or decisions that need evidence backing."
user-invocable: true
argument-hint: '[topic] - Optional: --research_depth=[overview|detailed|comprehensive|deep-dive] --skill-for=[agent-name]'
---

# NW-RESEARCH: Evidence-Driven Knowledge Research

**Wave**: CROSS_WAVE
**Agent**: Nova (nw-researcher)
**Command**: `*research`

## Overview

Systematic evidence-based research with source verification. Cross-wave support providing research-backed insights for any nWave phase using trusted academic|official|industry sources.

Optional `--skill-for={agent-name}` distills research into a practitioner-focused skill file for a specific agent.

## Orchestration: Trusted Source Config

At orchestration time, before invoking the researcher subagent:

1. **Read Config** — Read `.nwave/trusted-source-domains.yaml` from the project root. Gate: file read attempted.
2. **Seed If Missing** — If file missing, write it from the defaults in `## Default Trusted Sources` below, then notify the user: "Seeded `.nwave/trusted-source-domains.yaml` with defaults (7 categories, 42 trusted domains, 5 excluded). Edit the YAML directly to customize." Gate: file exists.
3. **Embed Config** — Embed the YAML content inline in the researcher subagent Task prompt so the agent receives trusted source config via prompt context. Gate: YAML present in Task prompt.

## Agent Invocation

@nw-researcher

Execute \*research on {topic} [--skill-for={agent-name}].

**Configuration:**
- research_depth: detailed # overview/detailed/comprehensive/deep-dive
- source_preferences: ["academic", "official", "technical_docs"]
- output_directory: docs/research/
- skill_for: {agent-name} # Optional: distilled skill for specified agent
- skill_output_directory: ~/.claude/nWave/skills/{agent-name}/

## Output Management

The researcher MUST create the output file in the FIRST 5 turns with a document skeleton (title, sections, placeholders). All subsequent findings are written DIRECTLY to this file as they are gathered — never held only in context.

If the agent is interrupted or runs out of turns, the output file contains all work done so far. This is the researcher's equivalent of the crafter's "commit early, commit often."

1. **Skeleton** — By turn ~5: Create output file with title, sections, and placeholders. Gate: output file exists.
2. **First Findings** — By turn ~10: Write initial gathered findings to file. Gate: file has substantive content.
3. **Ongoing Writes** — By turn ~25: Write all gathered findings so far. Gate: no findings held only in context.
4. **Synthesize** — By turn ~35: Stop gathering, begin synthesizing. Gate: synthesis section started.
5. **Polish** — Turn ~45+: Polish and finalize only. Gate: research document complete.

## Success Criteria

**Research:**
- [ ] All sources from trusted source domains from prompt context
- [ ] Cross-reference performed (3+ sources per major claim ideal, 2 acceptable, 1 authoritative minimum)
- [ ] Research file created in docs/research/
- [ ] Citation coverage > 95%
- [ ] Average source reputation >= 0.80

**Distillation (if --skill-for specified):**
- [ ] Skill file created in ~/.claude/nWave/skills/{agent-name}/
- [ ] 100% essential concepts preserved
- [ ] Self-contained with no external references
- [ ] Token budget respected (<5000 tokens per skill)

## Next Wave

**Handoff To**: Invoking workflow
**Deliverables**: Research document + optional skill file

## Examples

### Example 1: Standalone research
```
/nw-research "event sourcing patterns" --research_depth=detailed
```
Nova researches event sourcing from trusted sources, cross-references 3+ sources per claim, produces comprehensive research document.

### Example 2: Research with agent skill
```
/nw-research "mutation testing methodologies" --skill-for=software-crafter
```
Nova researches mutation testing, distills into practitioner-focused skill file at ~/.claude/nWave/skills/software-crafter/.

## Expected Outputs

```
docs/research/{category}/{topic}-comprehensive-research.md
~/.claude/nWave/skills/{agent}/{topic}-methodology.md    (if --skill-for)
```

## Default Trusted Sources

The following YAML is the default content for `.nwave/trusted-source-domains.yaml`. It is seeded automatically when the file does not exist.

```yaml
# Trusted Source Domains for Evidence-Driven Research
# Used by knowledge-researcher agent to validate source credibility

# High-reputation academic and research sources
academic:
  description: "Peer-reviewed academic and research institutions"
  domains:
    - "*.edu"
    - "*.ac.uk"
    - "scholar.google.com"
    - "arxiv.org"
    - "pubmed.ncbi.nlm.nih.gov"
    - "researchgate.net"
    - "ieee.org"
    - "acm.org"
    - "springer.com"
    - "sciencedirect.com"
    - "jstor.org"
    - "nature.com"
    - "science.org"
  reputation: high
  verification_requirements:
    - peer_review_preferred
    - citation_tracking
    - author_credentials

# Official standards bodies and government sources
official:
  description: "Government, standards organizations, and official documentation"
  domains:
    - "*.gov"
    - "*.gov.uk"
    - "w3.org"
    - "ietf.org"
    - "iso.org"
    - "nist.gov"
    - "docs.microsoft.com"
    - "docs.oracle.com"
    - "docs.python.org"
    - "docs.oracle.com/javase"
    - "kubernetes.io/docs"
    - "docker.com/docs"
  reputation: high
  verification_requirements:
    - official_publication
    - version_tracking
    - standards_compliance

# Industry leaders and recognized experts
industry_leaders:
  description: "Established technology companies and recognized industry experts"
  domains:
    - "github.com"
    - "stackoverflow.com"
    - "martinfowler.com"
    - "refactoring.guru"
    - "enterpriseintegrationpatterns.com"
    - "microservices.io"
    - "12factor.net"
    - "reactiv

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.