create-repo-mindmap

name	create-repo-mindmap
description	Analyze a repository and generate a Knowledge Dungeon subject folder (dungeon.json + room notes/artifacts) for architecture, systems, features, and workflow learning. Use when user asks to build a playable repo mindmap, onboarding dungeon, architecture study map, or phase-ready creator/scribe/archaeologist subject from code.
argument-hint	--repo-path . --depth balanced --name "My Project" --entry-phase scribe
user-invocable	true

Create Repository Mindmap

Generate a complete Knowledge Dungeon subject from a repository so users can explore code architecture as a playable topic graph.

When To Use

• User asks for a repo mindmap or architecture map from source code.
• User wants a Knowledge Dungeon import folder generated from a codebase.
• User wants phase-ready output (creator, scribe, or archaeologist).
• User wants onboarding/study content from a local repo or cloned project.

Inputs

• --repo-path (default .): repository path to analyze.
• --depth (default balanced): light, balanced, deep.
• --name (optional): display name for subject.
• --output (default maps/{project-name}-mindmap): destination folder.
• --entry-phase (default scribe): creator, scribe, archaeologist (review should be treated as alias for archaeologist).
• --review-ready (flag): alias for --entry-phase archaeologist.

Required Output Structure

maps/{project-name}-mindmap/
├── dungeon.json
├── README.md
└── rooms/
    ├── room-*/
    │   ├── notes.txt
    │   └── artifact.md   # required for archaeologist-ready output
    └── ...

Procedure

1. Analyze repository structure and tech stack.
2. Identify core domains and user-facing systems.
3. Build a 30-40 room topic graph with meaningful edges.
4. Write validation-ready notes for each room.
5. Apply phase profile:
   • creator: structure-first rooms (Created state)
   • scribe: complete note content for study progression
   • archaeologist: review-ready artifacts + metadata
6. Emit dungeon.json, rooms/*/notes.txt, and README.md.
7. For archaeologist-ready output also emit rooms/*/artifact.md and set artifact/review metadata in dungeon.json.
8. Print concise load instructions for web and desktop usage.

Accuracy Protocol (Required)

Follow this protocol every run to reduce hallucinations and improve map quality.

1. Inventory first, summarize second:

• Enumerate top-level folders and key build/test/config files.
• Identify primary entrypoints, main runtime modules, and persistence/state locations.

2. Extract evidence before writing topic claims:

• Every room topic must be traceable to real files, symbols, or scripts.
• Do not invent frameworks, services, or layers not present in repo evidence.

3. Prioritize high-signal modules:

• Prefer directories with dense imports/usages, test coverage, and core app flow.
• De-prioritize generated output, vendored files, and low-signal stubs.

4. Reconcile terminology:

• Use the repository's actual naming conventions for topics (feature names, module names, domain terms).

5. Run a final consistency pass:

• Ensure room notes, room relationships, and summary README all describe the same architecture model.

Room Planning Rules

Target 30-40 rooms with this distribution (adjust +/- 2 per category based on repo size):

• Architecture/Core domains: 6-8
• Features/Product systems: 6-8
• Runtime/Game/App systems: 5-7
• Data/State/Persistence: 4-6
• Tooling/Build/Test/Workflow: 4-6
• Platform/Integration (desktop/web/api/external): 3-5

Root room requirements:

• Use project name as root topic.
• Root note should explain purpose, constraints, and major subsystems.

Room naming rules:

• Keep topics concrete and codebase-specific.
• Prefer Domain: Specific Topic for clarity when needed.
• Avoid vague names like Utilities, Misc, Core Stuff.

Edge Construction Rules

Graph quality matters as much as note quality.

• Ensure full connectivity from root (no isolated rooms).
• Use hierarchical edges for ownership/decomposition.
• Add cross-links only when there is real runtime/data/test/build coupling.
• Avoid clique-like over-linking; prefer sparse, meaningful edges.
• Keep edge semantics explainable in one sentence.

Minimum edge targets:

• At least rooms - 1 structural edges (tree backbone).
• At least 20% additional cross-links for non-trivial repos.

Notes Format (Strict)

Each rooms/<room-id>/notes.txt must include these sections exactly:

1. Summary
2. Key Points
3. Recall Question

Quality rules:

• 120+ words recommended for strong study value.
• Key Points should be bullet-style and specific.
• Recall Question should test architecture understanding, not trivia.
• Include concrete repository evidence in prose (paths, symbols, or scripts).

Suggested template:

Summary
<1-2 paragraphs on purpose, role in architecture, and interactions>

Key Points
- <key mechanism>
- <important dependency or integration>
- <tradeoff, constraint, or failure mode>

Recall Question
<question that requires reasoning about this room's relationships>

Evidence Requirements

For each room, capture at least two evidence anchors from the repo:

• File paths
• Important symbols (functions/classes/types)
• Commands/scripts/config entries

If evidence is weak, either:

• merge the topic into a stronger adjacent room, or
• mark it as low-confidence and reduce room count instead of inventing detail.

Depth Behavior

• light: concise notes, fewer cross-links, broader conceptual coverage.
• balanced: default depth with concrete evidence and moderate cross-links.
• deep: denser notes, implementation details, stronger coupling explanations, more recall-oriented questions.

Determinism And IDs

• Use stable room ids derived from normalized topic names (slug + stable suffix).
• Keep output deterministic for same input/depth when possible.
• Preserve room ordering by domain buckets, then topic name.

Validation Checklist (Before Final Output)

Must pass all checks:

1. dungeon.json parses and includes all referenced room ids.
2. Every room has notes.txt and required section headers.
3. Graph has no isolated nodes and has root reachability.
4. Room count matches requested depth/scope (target 30-40 unless explicitly reduced).
5. Topic claims are backed by real repository evidence.
6. README instructions match current Knowledge Dungeon load flow:

• web: refresh subjects, then load by subject name
• desktop: refresh subjects, then load from list or import folder via Admin tools

7. Phase profile metadata is internally consistent (creator vs scribe vs archaeologist).

Reference

• Detailed output contract, mini-schema, and worked examples: Dungeon Output Spec

Content Expectations

• Cover architecture, technology, features, systems, workflow, and state/persistence.
• Connect related rooms with graph edges (cross-links where useful).
• Keep notes educational and specific to analyzed code (not generic filler).
• Ensure notes are compatible with Knowledge Dungeon validation expectations.

Archaeologist-Ready Rules

When --entry-phase archaeologist (or --review-ready) is requested, ensure:

• dungeon.phaseState is ArchaeologistUnlocked or ArchaeologistActive.
• Room summary status is ArtifactCollected.
• Room metadata includes:
  • validationState.finalPass: true
  • non-empty artifactMarkdown
  • initialized reviewPassCount (typically 0)

For concrete examples of archaeologist-ready room metadata and artifact structure, see:

• Dungeon Output Spec: Worked Example

Phase Profile Metadata

Ensure dungeon.phaseState and room summary status match the requested entry phase:

• creator
  • dungeon.phaseState: CreatorActive
  • room summary status: Created
  • artifact.md: not required
• scribe
  • dungeon.phaseState: ScribeActive
  • room summary status: Created
  • artifact.md: optional
• archaeologist (or review alias)
  • dungeon.phaseState: ArchaeologistUnlocked or ArchaeologistActive
  • room summary status: ArtifactCollected
  • artifact.md: required for every room

If exact enum names differ in the target repository, use that repository's canonical persisted values.

Artifact Markdown Format

For archaeologist-ready output, keep each room artifact structured and non-trivial:

# <Room Topic>

## Snapshot
<1-2 sentence summary>

## Why It Matters
<2-3 sentence architectural or learning significance>

## Cross-References
- <related room/topic>

Response Template

Use this summary format at completion:

✅ Subject created: maps/{project-name}-mindmap/

Generated:
- Rooms: <count>
- Edges: <count>
- Phase profile: <creator|scribe|archaeologist>

Next steps:
1. Open Knowledge Dungeon
2. Refresh subjects / load by subject name (or copy into local subject storage first)
3. Explore

Notes

• Prefer deterministic, analysis-driven room naming and grouping.
• If repository is very large, focus on highest-signal modules first.
• If requested scope is a monorepo subproject, honor --repo-path exactly.
• Generated repo mindmaps are image-ready: after loading a subject in Knowledge Dungeon, users can add room images during Scribe phase and then export the subject folder from desktop mode for sharing.