how

Files (1)

• SKILL.md

SKILL.md (first lines)

# Investigate Feature

The user will provide a short feature description. Trace how it works on whatever stack is present (backend, mobile/frontend, or both), explain it with file paths, then generate the diagram HTML.

## Phase 1: Research

Do not search the repo yourself first. Launch **parallel Task subagents** in one turn, then stitch their results. These are built-in agent types, not skills in this pack. The names below are Cursor's; in Claude Code use `Explore` for `explore` and `general-purpose` for `generalPurpose`.

1. Skim only enough to guess which surfaces exist (mobile, backend, or both).
2. Start 2–3 subagents together:

| Subagent | Type | Thoroughness | Job |
| --- | --- | --- | --- |
| Keywords | `explore` | medium | Files, symbols, and call sites matching the feature keywords |
| Backend | `explore` | medium | Routes, handlers, jobs, services, models, tables, queues — skip if no backend |
| Mobile / UI | `explore` | medium | Screens, navigation, view models, hooks, stores, clients, native modules — skip if no UI |

3. If one path is still unclear after they return, launch one `generalPurpose` follow-up to trace that path. Do not start the write-up until the first wave is back.

Each subagent should return: relative paths, package/app name, key functions, and how the files connect. Skip layers that are not in the repo.

## Phase 2: Explain

```
## Feature: [Name]

### How it works
[2-3 sentence end-to-end summary]

### Flow
1. Step → `file path` → what happens
...

### Key Files
| File | Project | Role |
|------|---------|------|
| `path/to/file` | app-or-package | What it does |
```

Add only the sections that research found:

- **Screens / Navigation** — screen, route, how the user gets there
- **Client state** — store, hook, view model
- **Types** — important types or props
- **Database tables** — only if the feature reads or writes a DB

## Phase 3: Diagrams

Write one HTML file: header "[Feature Name] — Codebase Investigation", sticky tab bar, Architecture open first.

| Tab | Include when... |
|-----|-----------------|
| Architecture | Always (C4: Context, Container, Component) |
| Sequence | Always |
| File Graph | Always |
| Activity | Conditional logic, branching, or error paths |
| ERD | Reads or writes database tables |
| State Machine | An entity, screen, or flow has a status/state lifecycle |

### Tab 1: Architecture Overview (C4)

Draw the feature with the C4 model: Context, Container, Component. One Mermaid diagram per level (`C4Context`, `C4Container`, `C4Component`). Do not mix levels. Skip C4 Code — files go on File Graph.

Level switcher inside this tab: **Context** | **Container** | **Component**. Default **Container**. Omit a level only when research found nothing for it.

| Level | Show | Nodes |
| --- | --- | --- |
| Context | People and systems around the feature | `Person`, `Person_Ext`, `System`, `System_Ext`, `SystemDb`, `SystemQueue` |
| Container | Deployable pieces | `Container`, `Container_Ext`, `ContainerDb`, `ContainerQueue` in a `System_Boundary` |
| Component | Modules inside the container that owns the feature | `Component`, `Component_Ext`, `ComponentDb` in a `Container_Boundary` |

A mobile app, web app, API, worker, and database are all containers. Screens, view models, routers, and domain services are components. Use `Rel(from, to, "label")` or `Rel(from, to, "label", "tech")`. Prefer real protocols (`HTTPS`, `SQL`, `navigation`). No `[]` or `<` in titles or labels.

```
C4Container
title Container diagram for Feature
Person(user, "User", "Starts the feature")
System_Boundary(sys, "This system") {
  Container(mobile, "Mobile app", "React Native", "Screens and local state")
  Container(api, "API", "Node.js", "Handles the request")
  ContainerDb(db, "Database", "PostgreSQL", "Stores records")
}
Rel(user, mobile, "Taps action")
Rel(mobile, api, "Calls API", "HTTPS")
Rel(api, db, "Reads and writes", "SQL")
```

### Tab 2: Sequence Flow

Primary use case, chronological. Participants are screens, view models, services, or files. Solid arrows = sync, dashed = async/events/navigation. Group into phases.

### Tab 3: Activity Diagram (conditional)

Branching and error paths. Swim lanes by screen or service. Label each branch.

```json
{
  "swimLanes": [
    { "name": "ServiceA", "file": "path/to/ServiceA.ts" }
  ],
  "nodes": [
    { "id": "start", "type": "start" },
    { "id": "validate", "type": "action", "label": "validate(input)", "lane": "ServiceA", "file": "path/to/file.ts" },
    { "id": "isValid", "type": "decision", "label": "is valid?", "lane": "ServiceA" },
    { "id": "end", "type": "end" }
  ],
  "edges": [
    { "from": "start", "to": "validate" },
    { "from": "validate", "to": "isValid" },
    { "from": "isValid", "to": "end", "label": "yes" }
  ]
}
```

### Tab 4: ERD (conditional)

Tables used by the feature. Mark PK/FK, cardinality, and `usedByFeature` on columns. Include the model or migration path.

```json

From Spice-Z/yugo-stack, MIT.

More from Spice-Z/yugo-stack