research

name	research
description	Survey external sources on a topic and maintain living research digests. Workspace digest is tracked; project digest lives in the manifest repo.

Research

Usage

/research <topic>                      # Add to workspace digest (default)
/research --scope project <topic>      # Add to project digest
/research --ingest <url>               # Extract takeaways from a URL
/research --refresh                    # Re-survey known topics, prune stale entries

Overview

Lifecycle position: Utility — not tied to the per-issue lifecycle. Use any time to survey external sources or maintain research digests.

Maintain living research digests that capture external best practices, emerging techniques, and relevant developments. This is external research — surveying sources outside the workspace. For project introspection, use gather-project-knowledge.

Digests

Two digests, each git-tracked so they're shared across agents and sessions:

Workspace digest

Location: .agent/knowledge/research_digest.md (git-tracked in the workspace repo; create with the digest format below if it doesn't exist)

Topics relevant to any project using this workspace:

• Agent workflow patterns and multi-framework coordination
• CI/CD for AI-assisted development
• Governance automation and enforcement patterns
• ROS 2 build system and tooling developments
• Worktree and git workflow patterns

Project digest

Write path: .agents/workspace-context/research_digest.md (in the manifest repo, where the file is git-tracked — commit there) Read path: .agent/project_knowledge/research_digest.md (workspace symlink to manifest repo's .agents/workspace-context/; may not exist until setup_layers.sh creates the symlink)

Topics specific to the project domain:

• ROS 2 ecosystem developments (new packages, API changes)
• Domain-specific developments (marine autonomy, hydrography, sensors)
• Relevant conference papers or technical reports

Digest Format

# Research Digest: <scope>

<!-- Last updated: YYYY-MM-DD -->
<!-- If older than 30 days, consider running /research --refresh; entries older than 90 days should be flagged for review -->

## <Topic Title>

**Added**: YYYY-MM-DD | **Sources**: [link1](url), [link2](url)

Key takeaways:
- <concise finding>
- <concise finding>

**Relevance**: <why this matters to the workspace/project>

---

## <Next Topic>
...

Workflow

Worktree setup

The worktree type depends on the scope:

• Workspace scope (default): use a --skill research worktree — no issue needed.

  .agent/scripts/worktree_create.sh --skill research --type workspace
  source .agent/scripts/worktree_enter.sh --skill research
  

• Project scope (--scope project): the project digest lives in the manifest repo, so you need a GitHub issue and a layer worktree targeting that repo.

  .agent/scripts/worktree_create.sh --issue <N> --type layer --layer <layer> --packages <manifest-repo>
  source .agent/scripts/worktree_enter.sh --issue <N>
  cd <layer>_ws/src/<manifest-repo>
  

Adding research (/research <topic>)

1. Set up the worktree for the appropriate scope (see above)
2. Search the web for current information on the topic
3. Read and synthesize relevant sources
4. Check the existing digest for related entries — update rather than duplicate
5. Append or update the entry in the appropriate digest
6. Update the "Last updated" timestamp
7. Commit in the correct repo: workspace digest commits go in the workspace repo; project digest commits go in the manifest repo (not the workspace)
8. Push and create a PR: git push -u origin HEAD && gh pr create --fill
9. Clean up the worktree when done

Ingesting a URL (/research --ingest <url>)

1. Set up the worktree for the appropriate scope (see above)
2. Fetch and read the URL content
3. Extract key takeaways relevant to the workspace or project
4. Determine scope (workspace or project) from content — or ask if unclear
5. Append to the appropriate digest
6. Commit, push, create PR, and clean up

Refreshing (/research --refresh)

1. Set up the worktree for the appropriate scope (see above)
2. Read both digests
3. For each entry, check if it's still current:
   • Search for updates on the topic
   • Update findings if new information exists
   • Mark as stale or remove if no longer relevant
4. Update timestamps
5. Commit, push, create PR, and clean up

Guidelines

• External sources only — this skill surveys the web, papers, docs, and community resources. It does not scan the workspace codebase.
• Concise entries — each topic should be 5-15 lines. The digest is a reference, not a literature review.
• Cite sources — every entry needs at least one link.
• Dedup — check for existing entries on the same topic before adding. Update existing entries rather than creating duplicates.
• Commit each update — so the digest history is traceable.
• Staleness — entries older than 90 days without a refresh should be flagged for review. Fast-moving topics (ROS 2 releases) may need shorter windows.