Research Lifecycle

This runbook defines the lifecycle for research documents produced by the SecurityV0 team and its agents. It ensures that findings don't get lost, decisions are explicit, and proposals surface into GitHub for visibility and prioritisation.

Why This Exists

Research docs accumulate. Without a lifecycle, good findings sit in docs/architecture/research/ unread, decisions never get made, and the same problems get re-researched. This runbook makes the lifecycle explicit and enforces it on every research PR.

Lifecycle States

idea → research-in-progress → research-complete → adopted
                                                 → deferred
                                                 → rejected

Status	Meaning	Who sets it
idea	Raw concept, not yet researched. May live as a GitHub Discussion or a stub doc.	Anyone
research-in-progress	Active investigation, document is incomplete.	The agent or human doing the research
research-complete	Findings are documented, analysis done. A decision is pending.	Researcher, on PR merge
adopted	The proposal has been formally committed to. A GitHub issue exists and work is planned or in progress.	PO or architect
deferred	Conscious decision to not act now. Revisit condition noted.	PO or architect
rejected	Investigated and ruled out. Reason documented.	PO or architect

Required Frontmatter

Every file in docs/architecture/research/ must include these fields in its YAML frontmatter:

---
date: YYYY-MM-DD         # Date research was started or last significantly updated
type: research           # Always "research"
status: <lifecycle>      # One of: idea, research-in-progress, research-complete, adopted, deferred, rejected
source: <name>           # Agent name (echo, delta, blue, charlie) or "human"
tags: [...]              # Topic keywords
priority: high|medium|low
description: "..."       # One-sentence summary
relates-to: [...]        # Obsidian-style links to related architecture docs
---

PRs that add or update a research doc without status in the frontmatter must not be merged. Reviewers should block on this.

Required Sections

For research-in-progress

No additional sections required beyond standard research body. The doc is a work in progress.

For research-complete

The doc must include a ## Next Action section before it can be merged:

## Next Action

**Status:** research-complete
**Decision needed from:** [person or role responsible]
**Options:**
1. Adopt — create GitHub issue to implement [Phase 1 description]
2. Defer — revisit after [specific milestone or date]
3. Reject — [reason if applicable]

**GitHub Issue:** [link — or "not yet created" if pre-merge]

For adopted, deferred, rejected

Update the ## Next Action section to record the decision:

## Next Action

**Status:** adopted
**Decision:** Adopted on 2026-03-11 by [name]
**GitHub Issue:** [link to implementation issue]

GitHub Issues for Proposals

When a research doc reaches research-complete and proposes new work, the researcher must create a GitHub Issue to make the proposal visible in project tracking:

1. Create a GitHub Issue in the relevant repository with the enhancement label
2. Title: Proposal: [short description]
3. Body: paste the ## Summary and ## Next Action sections from the research doc, plus a link to the full doc
4. Link the Issue URL in the ## Next Action section of the research doc under GitHub Issue:
5. Update docs/architecture/research/index.md

Note on GitHub Discussions: GitHub Discussions are currently disabled across all SecurityV0 repos. Issues are used instead. If Discussions are enabled in future, migrate the proposal category to a "Proposals" Discussion category and update this runbook.

Where to create Issues:

Proposal type	Repo
New connector or connector change	sv0-connectors
Platform feature or model change	sv0-platform
Documentation or process	sv0-documentation
Cross-cutting / architectural	sv0-platform (closest concern)

index.md

docs/architecture/research/index.md is the single scannable view of all research and its current status. It must be kept up to date.

Format:

| Document | Status | Date | Summary | Next Action |
|----------|--------|------|---------|-------------|
| [Title](link) | research-complete | 2026-03-11 | One-liner | Create issue |

Whenever a research doc's status changes, update index.md in the same PR.

Idea Capture (Pre-Research)

For ideas that aren't ready for a full research doc:

1. Create a GitHub Issue in the most relevant repo with the idea label
2. The Issue serves as the canonical home for the idea
3. If the idea is picked up for research, update the Issue with a link to the research doc and close it when research is complete

This prevents ideas from being lost in chat or session notes.

Agent Rules (Enforced)

Agents producing research docs (Echo, Delta, Blue, Charlie) must:

• Set status: frontmatter on every research file they create or update
• Include ## Next Action before marking a PR ready for merge at research-complete
• Create a GitHub Issue when the research proposes new platform or connector work
• Update docs/architecture/research/index.md in the same PR

Reviewers (Blue) must:

• Reject any research PR missing status: frontmatter
• Reject any research-complete PR missing ## Next Action
• Verify the ## Next Action section names a real decision-maker and actionable options