---
name: maraudersmapmd-skill
version: 1.1.0
description: >-
  Rewrite Markdown for readability and SQLite-backed sharded retrieval for MaraudersMapMD
  (Cursor, VS Code, Claude Code, Antigravity). Prefer fenced Mermaid for diagrams; use
  Context7 MCP for up-to-date Mermaid syntax when available. Triggers on readability rewrites,
  MaraudersMapMD formatting, GEO/AI-readable docs, and shards.db workflows.
---

# MaraudersMapMD Skill

## When to Use

- User asks to improve readability, rewrite for clarity, or optimize a Markdown document for scanning
- User asks to apply MaraudersMapMD formatting or make a document AI-readable / GEO-friendly
- User provides a Markdown document and asks for editorial polish
- User asks to keep sharded / SQLite-backed Markdown access in sync with a rewritten document

## MaraudersMapMD extension alignment (v1.1.28+)

- **Skill install (from the extension toolbar / “Copy Readability Prompt”)** — The extension’s `buildReadabilityPrompt()` in `src/ai/aiService.ts` does **not** embed the editorial instructions. It tells the agent to install or refresh this file from  
  `https://raw.githubusercontent.com/mandarange/MaraudersMapMD-skill/main/SKILL.md`,  
  compare the YAML **`version`** in the frontmatter to the remote copy, and then run this skill **as defined in SKILL.md**.
- **Typical install paths** — Cursor: `.cursor/skills/maraudersmapmd-skill/SKILL.md` (or legacy `.cursor/rules/maraudersmapmd-skill.mdc`); Claude Code: `.claude/skills/maraudersmapmd-skill/SKILL.md`; Antigravity IDE: `.agent/skills/maraudersmapmd-skill/SKILL.md`.
- **`docId` vs SQLite layout** — The extension derives `docId` as the Markdown filename **without** `.md` (`path.basename(filePath, '.md')`). For a rewritten file named `guide.rewritten_v1.md`, on-save artifacts go under `docs/MaraudersMap/guide.rewritten_v1/`. This skill’s SQLite ingest expects a **stable** directory `docs/MaraudersMap/guide/` containing `guide.rewritten_v*.md` (see `shards_db.py`). **Mitigation:** while iterating, avoid relying on extension on-save paths for the rewritten filename, or temporarily disable `ai.buildOnSave` for that file, or keep the canonical source as `guide.md` for extension output and treat `docs/MaraudersMap/guide/` + ingest as the SSOT for this skill.

## Canonical readability prompt (SSOT)

The block below is the **authoritative** rewrite instruction set. Apply it as-is. `${source}` is the user-provided Markdown.

You are an expert technical editor. Rewrite the Markdown to maximize readability and scan-ability while preserving meaning and intent.

Core requirements:

- Keep the final language the same as the original (do not translate). If mixed, use the dominant language.
- Never translate user-authored prose, headings, labels, or explanatory sentences into another language.
- If the source is Korean, output must remain Korean except for literals that are already in English (for example code, API names, CLI flags, product names, or quoted identifiers).
- Preserve all facts, constraints, and technical details. Do not add new information.
- Keep Markdown semantics correct (headings, lists, tables, code fences, links).
- Use the project's AI hint block format where it helps: "> [AI RULE]", "> [AI DECISION]", "> [AI TODO]", "> [AI CONTEXT]".
- Prefer short paragraphs, clear headings, and consistent numbering.
- Use tables for settings, options, or structured comparisons when helpful.
- Keep code blocks and inline code exactly as-is **except** ASCII visual regions handled per the classification rules below (Mermaid fences, Markdown tables, or intentional ASCII preservation).
- Classify and convert ASCII visual content (see "ASCII visual content classification"):
  - **Data tables** (box-drawing grids, aligned columns) → proper Markdown pipe tables.
  - **Process / architecture / sequence / ER-style relationships** → prefer a **fenced `mermaid` block** that faithfully models the source. Use **Mermaid-first** (see "Mermaid-first rule").
  - **Quantitative ASCII charts** (bars, sparklines, dense multi-series) → simple cases per "ASCII-to-chart rule"; otherwise keep ASCII and point to `Marauders_ASCII2Chart_Skill`.
- Remove fluff and redundancy; keep only what's necessary.
- Output ONLY the final Markdown. No commentary.

Formatting guidance:

- Ensure headings follow a clean hierarchy.
- Convert dense prose into bullet lists where it improves readability.
- Keep a concise top summary if the document is long.

SOURCE MARKDOWN (do not omit any content):

<<<BEGIN MARKDOWN
${source}
END MARKDOWN>>>

## Mermaid-first rule (with Context7)

- **Default** — When the source uses ASCII flowcharts, ER-like boxes, sequence-style interactions, or other **structural** diagrams, **rewrite** them into standard Markdown **fenced** diagrams:

  ````markdown
  ```mermaid
  …
  ```
  ````

- **Stay current** — If the **Context7** MCP (`user-context7`) is available, before emitting large or novel diagrams call **`resolve-library-id`** with `libraryName` `mermaid` (and a short query), then **`query-docs`** using a current library id such as `/mermaid-js/mermaid/v11_0_0` to confirm syntax (e.g. `flowchart` / `graph` TD or LR, `sequenceDiagram` with `alt` / `opt` / `loop`, `erDiagram`, `stateDiagram-v2`). Respect per-session tool call limits documented for that MCP.
- **Practical Mermaid 11 patterns** (verify in Context7 when unsure):
  - **Flow**: `flowchart TD` or `flowchart LR` (or `graph TD` / `graph LR`) with nodes, labeled edges, and `subgraph` for grouping.
  - **Sequence**: `sequenceDiagram`, explicit `participant` lines when order matters; `->>` / `-->>` for messages; `Note` / `alt` / `opt` / `loop` as needed.
  - **ER**: `erDiagram` with relationship cardinalities per Mermaid docs.
  - Use stable **node IDs** (ASCII alphanumeric / underscores); put human-readable text in **labels** (`["Label with spaces"]` or quoted strings) to avoid parse errors.
- **When not to force Mermaid** — If a faithful Mermaid diagram would be **much larger than the source**, lose **layout semantics**, or require **non-supported** notation, **keep** the ASCII in a fenced code block (plain text / monospace) and direct the user to **[Marauders_ASCII2Chart_Skill](https://github.com/mandarange/Marauders_ASCII2Chart_Skill)** for pixel-polished renders.
- **Companion** — Raster/diagram PNG workflows remain the responsibility of ASCII2Chart or manual assets; this skill does **not** require HTML capture for diagrams replaced by Mermaid.

## ASCII visual content classification

| Kind | Action |
|------|--------|
| Data table (borders, cells of scalar data) | Markdown pipe table (same row/column counts). |
| Structure / flow / ER / sequence (conceptual graph) | **Mermaid** in a fenced code block with language tag `mermaid` when faithful; else ASCII fence + ASCII2Chart note. |
| Simple quantitative chart (≤10 items, single series bars) | Markdown table + inline bar glyphs per ASCII-to-chart rule. |
| Complex charts | Keep ASCII; recommend ASCII2Chart. |

## Procedure

Follow these five phases in order.

### Original file protection rule

- The original source file must remain **untouched**. Never generate shards, indexes, or MaraudersMapMD artifacts **from** the original.
- Sharding, SQLite ingest, and optional extension artifacts target the **rewritten** file (`<base>.rewritten_v{N}.md`) only.
- The original is for fact-checking only.

Artifact paths (from the rewritten file):

- Active rewritten Markdown: `<base>.rewritten_v{N}.md` (alongside the source unless the user specifies otherwise).

> [AI RULE] `<docId>` for `docs/MaraudersMap/<docId>/` is the **normalized base name** (strip `.rewritten_v{n}`). Example: `guide.rewritten_v1.md` → docId `guide`. Never use version-suffixed directory names like `guide_v2` as docId.

### Language lock rule (highest priority)

- Preserve source language; no translation unless explicitly requested.
- Korean stays Korean except existing English technical literals.
- Mixed-language segments stay as in the source unless the user asks to normalize.
- Language drift is a blocking error — fix before completion.

> [AI RULE] Korean rewritten into English (or vice versa) without an explicit user request is a hard failure.

### SQLite retrieval and cache-aside (single rule block)

**Primary store** — `docs/MaraudersMap/shards.db` (unified SQLite + FTS5). Query it **before** scanning long Markdown for facts.

**Fallback order** — (1) SQLite keyword / BM25; (2) `<base>.rewritten_v{N}.md`; (3) original source only for verification.

**Optional extension files** — `sections/*.md`, `index.json`, `ai-map.md` under `docs/MaraudersMap/<docId>/` may exist (from MaraudersMapMD on-save). They are **not** the primary retrieval path for this skill. Legacy `shards.json` paths are **disabled**. Delete any artifacts clearly generated from the **original** source by mistake.

**Commands**

- Init once: `python shards_db.py --init --map-root docs/MaraudersMap`
- After each rewrite update: `python shards_db.py --ingest docs/MaraudersMap/<docId> --map-root docs/MaraudersMap`
- Per-doc search: `python shards_search.py --db docs/MaraudersMap/shards.db --doc "<docId>" --query "<text>" --top 5`
- Cross-doc: `python shards_search.py --db docs/MaraudersMap/shards.db --query "<text>" --top 5`
- Exact keyword: `python shards_search.py --db docs/MaraudersMap/shards.db --keyword "<kw>" --doc "<docId>"`

**Retrieval routing** — Choose the fastest path:

1. **SQLite keyword** — exact keyword in section metadata.
2. **SQLite FTS5** — ranked `BM25` via `--query`.
3. **Fallback** — read `<base>.rewritten_v{N}.md`, then original if still unresolved.

> [AI RULE] Always try SQLite first. For **independent** multi-document rewrites, use **parallel** tool use; sequential work is a performance bug.

### Accuracy guardrails

- Do not invent facts not present in SQLite hits, rewritten Markdown, or the original.
- If SQLite and rewritten Markdown disagree, trust the rewritten Markdown and **re-ingest**.
- If rewritten text is ambiguous, confirm against the original before answering.

### ASCII-to-Markdown-table conversion rule

When ASCII art is a **data table** (box-drawing `+---+`, `│`, aligned columns):

- Detect header and separator rows; emit GitHub-flavored pipe tables.
- Preserve every cell; no row/column loss.

> [AI RULE] Row/column count must match the ASCII source.

### ASCII-to-chart conversion rule

When ASCII represents **quantitative** charts (bar fills `█`, axis labels, etc.):

- **Simple** (≤10 items, single series) → Markdown table with numeric values (optional compact bar in inline code).
- **Complex** multi-series / pie / sparklines → keep ASCII fenced; recommend **Marauders_ASCII2Chart_Skill**.

> [AI RULE] Every numeric value in the source chart must appear in the output; no dropped data points.

### Workspace safety (README)

- When working in a **user’s project**, do **not** modify that project’s **root `README.md`** as part of this workflow unless the user explicitly asks. Confine edits to the Markdown under rewrite, MaraudersMap outputs, and this skill’s companion scripts as needed.

### Artifact hygiene

- Remove stale MaraudersMap outputs (old rewritten versions, orphan dirs) so `docs/MaraudersMap/<docId>/` stays coherent.
- **SQLite** lives at `docs/MaraudersMap/shards.db`.
- **Embedded PNGs** (only if present after ASCII2Chart or manual assets) go under `docs/MaraudersMap/<docId>/images/` with stable, kebab-case names; optional `render-html/` for companion raster pipelines.
- Do not create duplicate docId directories for the same logical document.

### Final honest review

- Before handing off, audit against these rules and fix gaps.

### Phase 1 — Baseline capture

Read the original and any existing rewritten file. Do not rewrite or generate artifacts from the original yet.

### Phase 2 — Create working copy

- **Base** — strip `.rewritten_v{n}` from the filename: `guide.rewritten_v1.md` → `guide`.
- **Next version** — first run `v1`; else max existing + 1.
- **Path** — `temp/temp_<base>.rewritten_v{N}.md`. Normalize final name to `<base>.rewritten_v{N}.md` (no chained `.rewritten.rewritten`).
- Edit **only** the working copy; never the source.

### Phase 3 — Skeleton

Flat heading list with one-line purpose per heading; fix `#` / `##` / `###` skips; add a short summary for long docs.

### Phase 4 — Rewrite and SQLite ingest

1. Rewrite per the **canonical prompt** (tables, bullets, **Mermaid** where appropriate, language lock).
2. Convert ASCII data tables and simple charts per rules; defer heavy raster work to ASCII2Chart.
3. Move the finished file to `<base>.rewritten_v{N}.md`.
4. `python shards_db.py --ingest docs/MaraudersMap/<docId> --map-root docs/MaraudersMap`

Parallelize across **documents**; within one document keep rewrite → ingest sequential.

### Phase 5 — Verification and cleanup

1. SQLite keyword / BM25 spot-checks return expected sections.
2. On intentional miss, fallback to rewritten file works.
3. If the doc embeds **PNGs**, paths resolve and files exist.
4. Run the checklist.

Then:

- Normalize rewritten filename.
- With multiple docs, ingest in parallel, then `python shards_db.py --status --map-root docs/MaraudersMap`.
- Delete `temp/` working files.
- Remove stale duplicate docId dirs.
- Confirm: untouched original, one active `<base>.rewritten_v{N}.md`, updated `shards.db`.

### Sync rule

Whenever the rewritten file changes:

1. Regenerate extension artifacts if the user relies on MaraudersMapMD on-save for that file.
2. `python shards_db.py --ingest docs/MaraudersMap/<docId> --map-root docs/MaraudersMap`
3. Verify SQLite content matches the rewritten doc before continuing.

## Checklist

- [ ] Heading hierarchy correct; summary for long docs
- [ ] Short paragraphs; bullets where helpful; tables for structured comparisons
- [ ] No spurious hard breaks; tidy lists
- [ ] Names / commands / identifiers unchanged; typos fixed only when obvious
- [ ] AI Hint blocks only where warranted
- [ ] All source facts and constraints preserved
- [ ] Code and inline code unchanged except allowed ASCII/Mermaid conversions
- [ ] Every ASCII visual **classified** (table / Mermaid / simple chart / complex chart / preserved ASCII)
- [ ] Pipe tables match ASCII row/column counts when converted
- [ ] **Mermaid** blocks are syntactically plausible and labeled; if Context7 was available, syntax was checked for non-trivial diagrams
- [ ] **Non-Mermaid** structure diagrams either stay in ASCII fences or are called out for ASCII2Chart — no silent deletion
- [ ] Chart numeric data preserved per rules
- [ ] If **PNGs** are used: each exists, is referenced, and orphan cleanup did not remove active assets
- [ ] `<docId>` directory stable; no duplicate versioned docId folders
- [ ] Single active `<base>.rewritten_v{N}.md`; superseded versions removed intentionally
- [ ] Optional: `<!-- Converted from ASCII art: … -->` near non-obvious replacements
- [ ] Output language matches source; no unrequested translation
- [ ] Rewritten filename normalized
- [ ] Final output is Markdown only — no commentary