earthmanweb/swe-symbol-index

Workflow Initialization

If starting a new session, first read workflow initialization:

mcp__plugin_swe_serena__read_memory("wf/WF_INIT")

Follow WF_INIT instructions before executing this skill.

---

/swe-symbol-index [KEY]

Generate a tabular view of all symbols found in a feature's linked documentation memories, and insert it into the feature's main FEATURE_[KEY] memory as a "Related Docs" section after "Feature Overview".

Usage

/swe-symbol-index CALENDAR        # Index all CALENDAR linked docs
/swe-symbol-index BLOCKS           # Index all BLOCKS linked docs
/swe-symbol-index THEME_DISTRICT   # Index all THEME_DISTRICT linked docs

Purpose

• Provide a quick-reference symbol map for feature documentation
• Link each heading/symbol back to its source memory file
• Make feature navigation faster by surfacing structure of related docs

---

Stage 1: Validate Feature

Verify feature exists:

mcp__plugin_swe_serena__read_memory("index/INDEX_FEATURES")

Check: Feature key exists in registered features table.

If not found:

> Feature [KEY] not registered. Use /swe-feature-onboard [KEY] to register it first.

Exit skill with needs_clarification status.

---

Stage 2: Load Feature Memory

mcp__plugin_swe_serena__read_memory("feature/FEATURE_[KEY]")

Extract the "Related Memories" section (typically a table at the bottom of the feature memory). This contains the list of linked doc names (e.g., DOM_CALENDAR_DISTRICT, SYS_CALENDAR_ICS).

Build linked docs list from:

1. The Related Memories table in FEATURE_[KEY] (Memory column values)
2. The Quick Lookup row for this KEY in INDEX_FEATURES (INDEX Memory column)

Deduplicate the combined list. These are all the memory files to index.

---

Stage 3: Extract Symbols From Each Linked Doc

For each linked memory file, use Serena's symbolic tools with depth=1 to capture nested headings:

mcp__plugin_swe_serena__get_symbols_overview({
  relative_path: ".serena/memory/[memory_subdir]/[MEMORY_NAME].md",
  depth: 1
})

Depth Parameter Reference

| depth | Returns | |-------|---------| | 0 (default) | Top-level symbols only | | 1 | Top-level + immediate children (recommended for indexes) | | 2+ | Deeper nesting — rarely needed for memory docs |

Memory subdirectory mapping:

| Prefix | Subdirectory | | ---------- | ------------ | | DOM_ | dom/ | | SYS_ | sys/ | | REF_ | ref/ | | ARCH_ | arch/ | | INDEX_ | index/ | | SPEC_ | spec/ | | MAP_ | map/ | | FEATURE_ | feature/ | | WF_ | wf/ |

If get_symbols_overview fails for a memory (file not in .serena/memory/), try the plugin path:

mcp__plugin_swe_serena__get_symbols_overview({
  relative_path: "$SWE_PLUGIN_ROOT/memories/[subdir]/[MEMORY_NAME].md"
})

Collect from each file:

• All heading symbols (H2 ## and H3 ### level)
• Symbol name (the heading text)
• Symbol depth/level

---

Stage 4: Build the Related Docs Table

Construct a markdown table with the following format:

## Related Docs

| Memory                                         | Key Sections                                     | Description                         |
| ---------------------------------------------- | ------------------------------------------------ | ----------------------------------- |
| [DOM_CALENDAR_DISTRICT](DOM_CALENDAR_DISTRICT) | Board Meetings, School Year Dates, URL Routes    | District-specific calendar behavior |
| [SYS_CALENDAR_ICS](SYS_CALENDAR_ICS)           | ICS Feed Generation, Rewrite Rules, School Dates | ICS feed system documentation       |
| ...                                            | ...                                              | ...                                 |

Rules for building the table:

1. Memory column: Memory name as a markdown link [NAME](NAME) (Serena memory ref format)
2. Key Sections column: Comma-separated list of H2 heading symbols from that memory (max 5, pick most descriptive). Skip generic headings like "Overview", "Related Memories", "Execute These Steps".
3. Description column: Extract from INDEX_FEATURES or FEATURE_[KEY] Related Memories table description column. If not available, derive from the first H2 heading content.

---

Stage 5: Insert Into Feature Memory

Target location: First section after ## Feature Overview (or after the first table following the feature overview heading).

Check if "## Related Docs" already exists in FEATURE_[KEY]:

If exists — Replace it:

mcp__plugin_swe_serena__edit_memory("FEATURE_[KEY]", {
  needle: "## Related Docs\\n\\n\\|.*?(?=\\n## |\\Z)",
  repl: "<new Related Docs section>",
  mode: "regex"
})

If does not exist — Insert it:

Find the insertion point: after ## Feature Overview section's content (after the metadata table that follows it), before the next ## heading.

mcp__plugin_swe_serena__edit_memory("FEATURE_[KEY]", {
  needle: "<end of Feature Overview section content>",
  repl: "<end of Feature Overview section content>\n\n## Related Docs\n\n<table content>",
  mode: "literal"
})

Use edit_memory with literal mode when possible for precision. Use regex mode only when the exact text is uncertain.

---

Stage 6: Summary Report

Output to user:

## Symbol Index Complete: [KEY]

### Indexed Memories

| Memory | Symbols Found |
| ------ | ------------- |
| [name] | [count]       |
| ...    | ...           |

### Related Docs Table

[Show the generated table]

### Inserted Into

- `FEATURE_[KEY]` — after "Feature Overview" section

---

Skill Return

## Skill Return

- **Skill**: swe-symbol-index
- **Status**: success
- **Feature Key**: [KEY]
- **Memories Indexed**: [count]
- **Symbols Found**: [total count]
- **Next Step Hint**: WF_START

---

Exit

> **Skill /swe-symbol-index complete** - Related Docs table inserted into FEATURE_[KEY]

---

Troubleshooting

Feature not found

Feature [KEY] is not registered in INDEX_FEATURES.
Run: /swe-feature-onboard [KEY]

No Related Memories section

FEATURE_[KEY] has no Related Memories section. Cannot determine linked docs.
Consider running /swe-feature-update [KEY] first.

Symbol extraction fails for a memory

• Memory may not exist in .serena/memory/ or plugin memories/
• Try search_for_pattern as fallback to find heading patterns: ^##
• Log skipped memories in the summary report

Symbol extraction returns empty for code files

Not all language servers expose symbols equally. Known limitations:

| File Type | Symbol Quality | Fallback | |-----------|---------------|----------| | PHP | Excellent | — | | Python/TS/JS | Good | Named exports work; jQuery wrappers may be empty | | SCSS/CSS | Poor | Use search_for_pattern with ^\\.classname or ^\\$variable | | Markdown | Limited | Headings only (H2/H3) | | JSON/Config | None | Use Read or search_for_pattern |

When indexing code files (not memory docs), use depth=1 on get_symbols_overview and find_symbol to capture class methods and nested symbols. Fall back to search_for_pattern for SCSS/CSS assets.

No symbols found

> No heading symbols found in any linked docs for [KEY]. Table not inserted.

Exit with success status (no symbols is a valid result).