survey

name	survey
description	Multi-perspective codebase survey that produces beads and mermaid diagrams from code structure. Each agent perspective (prod, staging, dev, feature, PM) examines the same codebase at a different zoom level, creating tagged beads and a disagreement matrix.

Survey — Multi-Perspective Codebase Analysis

Run a structured survey of a codebase from multiple agent perspectives. Each perspective examines the same code at a different zoom level, produces findings as beads (tagged with --actor), and generates mermaid diagrams from the actual code structure.

Arguments

$ARGUMENTS

Arguments format: [repo-path] [--perspectives <list>] [--diagram-only] [--dry-run]

• repo-path: Path to the repo to survey (default: current working directory)
• --perspectives: Comma-separated list of perspectives to run (default: all). Options: prod, staging, dev, feature, pm
• --diagram-only: Skip bead creation, only generate mermaid diagrams
• --dry-run: Show what would be created without creating beads

If no arguments provided, survey the current working directory from all perspectives.

The Model

The survey is a graded filter bank — each perspective is a bandpass filter examining the same codebase at a different frequency:

Perspective	Zoom Level	What It Looks For	Actor Tag
Dev	High freq — individual functions/files	Dead code, unused imports, TODO debt, complexity hotspots	dev-agent
Prod	Mid-high — module/package patterns	Code smells, anti-patterns, dependency direction violations, error handling gaps	prod-agent
Staging	Mid — test/code correspondence	Fake tests, coverage gaps, test-prod divergence, mocked-but-never-real	staging-agent
Feature	Mid-low — cross-file/cross-package	API surface coherence, circular dependencies, feature flag debt, interface bloat	feature-agent
PM	Low freq — cross-repo patterns	Duplicated functionality across repos, abandoned experiments, scope overlap	pm-agent

The disagreement matrix (where perspectives conflict) is the most valuable output — it reveals concerns that no single perspective would catch alone.

Prerequisites

• mache in PATH (for code structure discovery and graph data)
• bd (beads) initialized in the target repo (bd init)
• ley-line (optional, for deeper AST analysis — falls back to mache if unavailable)
• tropo (optional, for topological significance — enhances but not required)

Workflow

Phase 1: Discovery — Build the Map

Before any perspective runs, build a structural map of the codebase using mache.

1.1 Check mache availability

which mache 2>/dev/null && echo "FOUND" || echo "NOT_FOUND"

If not found, ask the user for the path. If truly unavailable, fall back to manual exploration (Glob + Grep + Read), but warn that diagram generation will be limited.

1.2 Mount or use MCP

If mache is available, prefer MCP tools (mcp__mache__get_overview, mcp__mache__list_directory, etc.) for querying structure. If MCP is not configured, mount via FUSE:

mache mount --schema auto --writable=false "$REPO_PATH" .mache-mount/survey &
echo $! > .mache-mount/.pid

1.3 Get structural overview

Using mache MCP or FUSE mount, gather:

• Module/package list
• Entry points (main packages, exported APIs)
• Dependency graph (callers/callees)
• Type hierarchy
• File count and language breakdown

Store this as the base map — all perspectives will reference it.

1.4 Generate the structure diagram

From mache's graph data, generate a mermaid diagram of the codebase architecture:

# If mache MCP is available:
# Use get_overview, find_callers, find_callees, get_communities to build the graph
#
# If FUSE mount:
# Read .mache-mount/survey/packages/ or .mache-mount/survey/functions/
# Follow callers/ and callees/ virtual directories

Generate mermaid from the discovered structure:

graph TB
    subgraph "package-a"
        A1[funcA1] --> A2[funcA2]
    end
    subgraph "package-b"
        B1[funcB1]
    end
    A2 --> B1

Key rules for diagram generation:

• Diagrams are GENERATED from code, never hand-written
• Use mache's get_communities to identify natural subgraph boundaries
• Use find_callers/find_callees for edges
• Collapse internal details — show module-level by default, function-level on request
• Include dependency direction arrows (which package imports which)
• Mark any circular dependencies with red/dashed edges

Write the diagram to $REPO_PATH/docs/ARCHITECTURE_SURVEY.md (or update if it exists).

Phase 2: Perspectives — Run Each Lens

For each selected perspective, examine the codebase through that lens. Use the base map from Phase 1 as the starting point.

IMPORTANT: Each perspective runs as a focused analysis pass. Do NOT try to find everything — find the things that THIS perspective uniquely cares about.

2.1 Dev Perspective (--actor dev-agent)

Focus: individual functions and files.

• Scan for TODO/FIXME/HACK comments and assess staleness
• Identify functions over 50 lines (complexity hotspots)
• Find unused exports / dead code paths
• Check for hardcoded values that should be config
• Look at error handling: swallowed errors, bare panics, empty catch blocks

Label beads: --labels "perspective:dev,survey:<timestamp>"

2.2 Prod Perspective (--actor prod-agent)

Focus: module-level quality patterns.

• Check dependency direction: do lower layers import upper layers?
• Identify god packages (too many responsibilities)
• Look for anti-patterns: global mutable state, init() side effects (Go), circular imports
• Assess error propagation: are errors wrapped with context?
• Check for missing input validation at system boundaries

Label beads: --labels "perspective:prod,survey:<timestamp>"

2.3 Staging Perspective (--actor staging-agent)

Focus: test/code correspondence.

• For each package with tests, assess: do the tests test real behavior or just mock everything?
• Find packages with zero test coverage
• Look for test files that import mocks of the thing they're supposed to test
• Check integration test coverage vs unit test coverage
• Identify flaky test patterns (sleep-based synchronization, time-dependent assertions)

Label beads: --labels "perspective:staging,survey:<timestamp>"

2.4 Feature Perspective (--actor feature-agent)

Focus: cross-file and cross-package coherence.

• Using mache's graph, identify API surface boundaries
• Check for interface bloat (interfaces with 10+ methods)
• Find circular dependency cycles between packages
• Look for feature flags that are always true/false (dead branches)
• Assess whether related functionality is co-located or scattered

Label beads: --labels "perspective:feature,survey:<timestamp>"

2.5 PM Perspective (--actor pm-agent)

Focus: strategic/cross-repo patterns.

• If multiple repos are available (check rosary.toml or scan parent directory), look for duplicated functionality
• Identify abandoned experiments (directories with no commits in 30+ days)
• Check for README/doc staleness vs actual code state
• Look at commit velocity per package — which areas are active vs neglected?
• Assess: is the repo doing too many things? Should it be split?

Label beads: --labels "perspective:pm,survey:<timestamp>"

Phase 3: Bead Creation

For each finding, create a bead:

bd create "<finding title>" \
  --description "<what was found, why it matters, where it is>" \
  --actor "<perspective>-agent" \
  --labels "perspective:<perspective>,survey:<YYYY-MM-DD>" \
  --priority <0-4> \
  --type task

Priority mapping:

• P0: Security issue, data loss risk, broken functionality
• P1: Architectural violation, significant technical debt
• P2: Code quality issue, missing tests, anti-pattern
• P3: Style issue, minor improvement, documentation gap
• P4: Nitpick, optimization opportunity

Phase 4: Disagreement Matrix

After all perspectives run, produce the matrix. This is the most important output.

4.1 Cross-reference findings

Group findings by code location (file or package). For each location that has findings from 2+ perspectives, note the agreement/disagreement:

## Disagreement Matrix

| Location | Dev | Prod | Staging | Feature | PM |
|----------|-----|------|---------|---------|-----|
| pkg/auth | - | "god package" | "tests mock everything" | "API surface too wide" | - |
| pkg/worker | "50+ TODO comments" | - | "zero test coverage" | - | "duplicates pkg/runner" |
| cmd/server | - | "swallowed errors" | - | "circular dep with pkg/config" | - |

4.2 Identify curvature

Where 2+ perspectives flag the same location but for different reasons, that's a high-value signal. These locations have multi-dimensional problems that individual reviews would miss.

Highlight these in the output:

### High-Curvature Zones (multiple perspectives disagree)

1. **pkg/auth** — Prod sees a god package, staging sees fake tests, feature sees API bloat.
   This is likely a single root cause: the package grew without boundaries.
   → Suggested action: decompose into sub-packages with clear interfaces.

4.3 Write the matrix

Append the disagreement matrix to $REPO_PATH/docs/ARCHITECTURE_SURVEY.md (same file as the mermaid diagram).

Phase 5: Summary

Output to the user:

• Total findings per perspective
• Number of high-curvature zones
• Generated diagram location
• Bead IDs created (grouped by perspective)

Diagram Generation Details

From mache graph → mermaid

The key insight: mache already has the graph. It parses AST via tree-sitter, builds a call graph, identifies communities. We just need to render it as mermaid.

Module-level diagram (default):

• One subgraph per package/module
• Edges = import relationships between packages
• Edge weight = number of cross-package calls
• Communities (from get_communities) become subgraph clusters
• Circular dependencies highlighted with style annotations

Function-level diagram (on request, per-package):

• One node per exported function
• Edges = call relationships (from find_callers/find_callees)
• Color by complexity or test coverage if available

Terraform-specific (if .tf files detected):

• Module dependency graph
• Resource → provider mapping
• State file cross-references

Bidirectional flow

Code (source files)
  ↓ ley-line (tree-sitter AST parse)
  ↓ mache (graph projection, community detection)
  ↓ survey skill (multi-perspective analysis)
  ↓
  ├── mermaid diagrams (ARCHITECTURE_SURVEY.md)
  ├── beads (tagged findings per perspective)
  └── disagreement matrix (curvature signal)
  ↓
  agent acts on findings → mache write-back → source files updated
  ↓
  re-survey to verify (delta mode)

The diagrams are never hand-maintained. They are regenerated from code on each survey run. If the code changes, the diagram changes. This is the opposite of "draw a diagram then forget to update it."

Re-survey (Delta Mode)

When re-running on a repo that was previously surveyed:

1. Check for existing beads with survey:<previous-date> labels
2. For each previous finding, verify if it's still present
3. Auto-close beads for resolved issues: bd close <id> --reason "Resolved: no longer detected in survey <date>"
4. Only create new beads for new findings
5. Update the mermaid diagram
6. Show delta: what improved, what regressed, what's new

Cleanup

If mache was mounted via FUSE:

if [ -f .mache-mount/.pid ]; then
  kill "$(cat .mache-mount/.pid)" 2>/dev/null
  rm .mache-mount/.pid
fi
umount .mache-mount/survey 2>/dev/null || diskutil unmount .mache-mount/survey 2>/dev/null

Example Usage

# Full survey of current repo
/survey

# Only prod and staging perspectives
/survey . --perspectives prod,staging

# Just generate the diagram, no beads
/survey ~/work/monorepo --diagram-only

# Dry run — see what would be found
/survey --dry-run

# Re-survey to check progress
/survey  # will detect previous survey beads and run in delta mode

Relationship to Rosary

This skill is the manual trigger for what rosary will eventually automate. When rosary's reconciliation loop runs, it dispatches agents with specific perspectives — that's the automated version of this skill. The survey skill lets you run the same analysis interactively, on demand, for any repo.

The --actor tags on beads are the bridge: rosary can query bd list --labels "perspective:prod" to see what the prod lens found, regardless of whether a human ran /survey or rosary dispatched an automated prod-agent.