---
name: ami-manage-docs
description: Comprehensive documentation and knowledge manager. Architects new documentation, synchronizes wikis with code diffs, extracts session learnings and ADRs, and audits knowledge bases to prune obsolete notes.
allowed-tools: Bash, Read, Grep, Edit, Write
---

# Skill: Documentation & Knowledge Lifecycle Manager

When invoked, act as a **Documentation Manager & Knowledge Architect**. Your goal is to ensure project documentation is well-structured, kept in sync with code changes, enriched with high-signal architectural learnings, and clean of obsolete notes.

## Workflow

### 1. Mode Detection & Context Assessment
Analyze the repository state and user request to determine the required operational mode:

- **Mode A: Architecture & Creation (New / Overhaul)**
  - *Trigger:* Missing documentation, request for new docs/guides, or structural re-organization. -> Proceed to **Section A**.
- **Mode B: Synchronization & Update (Code Changes)**
  - *Trigger:* Code changes (`git diff`), modified APIs, updated features, or pre-push/PR checks. -> Proceed to **Section B**.
- **Mode C: Knowledge Lifecycle & Obsolescence Audit (Learnings Pruning)**
  - *Trigger:* Request to audit/clean documentation, accumulated stale notes in `docs/learning/` or `docs/external-references/`, or periodic maintenance. -> Proceed to **Section C**.
- **Mode D: Knowledge & ADR Harvesting (Session Learnings Extraction)**
  - *Trigger:* Post-feature, post-debugging, or pre-push capture of enduring architectural decisions, lessons, patterns, and gotchas from recent changes. -> Proceed to **Section D**.

---

## Mandatory Documentation Standards & Formatting Rules

The following standards apply across all modes (Architecture, Synchronization, Lifecycle Audits, and Learnings Harvesting) and MUST be strictly enforced:

1. **Strict Zero Flags Policy:**
   - Country flag emojis or flag graphics are strictly prohibited anywhere in documentation, README files, wikis, headers, badges, or language switchers.
   - Flags represent sovereign states and geopolitical entities, NOT languages. Associating a flag with a language introduces regional bias and geographic inaccuracy. Furthermore, flags render as broken letter pairs (`[U][S]`, `[E][S]`) or unprintable glyphs on Windows terminals, PowerShell, and desktop UI frameworks.
   - Always use clean semantic text links (`[English](#english) | [Español](#español)` or `[English](README.md) | [Español](README.es.md)`), standard ISO language codes (`EN`, `ES`), or unadorned headings (`## English`, `## Español`).
2. **Bilingual Navigation & HTML Anchors:**
   - When implementing bilingual documentation in a single file, provide explicit HTML anchors (`<a name="english"></a>`, `<a name="español"></a>`) directly above section headers to guarantee cross-platform anchor resolution on GitHub, GitLab, and local viewers without relying on vendor-specific slug generation.
   - For multi-file bilingual repositories, maintain separate symmetric bilingual files (`README.md` in English, `README.es.md` in Spanish) with reciprocal navigation links in the header.
3. **Local Path Privacy (Zero Path Leaks):**
   - Never leak absolute local machine paths (e.g., `C:\Users\...` or `/home/...`) in documentation, README files, architecture diagrams, command snippets, or error references.
   - Always use relative paths (e.g., `./scripts/build.ps1`), standard environment variables (e.g., `%LOCALAPPDATA%\AppName\Logs`), or generic placeholders (e.g., `/path/to/project`).
4. **Clean Shields.io Badges:**
   - Format badges using standard flat style (`style=flat`), official brand logos (`logo=...`), and white glyphs (`logoColor=white`).
   - Badges must reflect genuine technical metadata (languages, frameworks, platforms, test status, licenses).
   - Prohibit decorative flags, emojis, or non-semantic symbols inside badge labels or icons.
5. **Atemporal Quality Gate Directives (Zero Static Test Counts):**
   - Never hardcode fixed numerical test counts (e.g., '57 tests passing', 'run the 12 tests') in documentation, runbooks, README files, or verification guides. Static numbers become obsolete upon the first test addition or refactoring.
   - Formulate all verification steps dynamically and atemporally (e.g., 'verify that the full automated test suite passes with 100% success / zero regressions').
6. **Gender Neutrality & Inclusive Language in Spanish:**
   - In Spanish-language documentation, interfaces, release notes, and communications, use neutral phrasing (e.g., 'te damos la bienvenida', 'todo listo') and avoid gender-biased assumptions or binary gendered phrasing.

---

### Section A: Architecture & Creation (New / Overhaul)

1. **Scope Assessment:** Inspect root directory and documentation folders (`docs/`, `wiki/`), as well as AI guidance files (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.agents/`, `.gemini/`).
   - If documentation exists, adopt established patterns or propose a restructuring plan if fragmented.
   - If starting from scratch, infer layout from codebase structure and propose both human-facing documentation (`README.md`, `docs/`) and AI assistant guidance (`AGENTS.md`, `CLAUDE.md`).
2. **Alignment & Structure Proposal:**
   - Present proposed file hierarchy in chat and await explicit user approval before drafting or reorganizing files.
3. **Iterative Generation & Review:**
   - Strictly enforce the **Mandatory Documentation Standards** (Zero Flags, HTML Anchors, Path Privacy, Clean Badges, Atemporal Quality Gates, and Spanish Gender Neutrality).
   - Write files upon approval using clean Markdown and iterate on user feedback.

---

### Section B: Synchronization & Update (Code Changes)

1. **Locate & Cross-Reference:**
   - Scan human-facing documentation (`README.md`, `docs/`) AND AI guidance documents (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.agents/`).
   - Review working tree diffs and commit history to identify modified behaviors, parameters, endpoints, architecture shifts, new skills/agents, or setup steps.
   - **UI Mockups Living Specs:** If changes introduce or refactor user interfaces, verify whether an interactive mockup exists under `docs/mockups/<feature-slug>.html`. Link approved mockups within feature documentation or architectural guides as living design specifications.
2. **Propose Updates:**
   - **CRITICAL:** Do NOT modify files immediately. Present a clear summary of proposed updates across human docs and AI guidance files in chat and request explicit approval.
3. **Apply & Report:**
   - Write changes after approval, strictly enforcing the **Mandatory Documentation Standards** (Zero Flags, HTML Anchors, Path Privacy, Clean Badges, Atemporal Quality Gates, and Spanish Gender Neutrality).
   - Report updated files, or state if no documentation changes were needed.

---

### Section C: Knowledge Lifecycle & Obsolescence Audit (Learnings Pruning)

1. **Knowledge Inventory & Inspection:**
   - Scan `docs/learning/`, `docs/external-references/`, `docs/adr/`, `docs/architecture/`, and `docs/mockups/` against the current codebase and active dependencies.
2. **Tri-State Classification Matrix:**
   - **Category 1 (Active / Invariant):** Active architectural invariants, non-trivial gotchas, or enduring operational constraints. Keep intact.
   - **Category 2 (Consolidate / Subsumed):** Fragmented or redundant notes that should be merged into a formal ADR (`docs/adr/`) or centralized guide.
   - **Category 3 (Obsolete / Ephemeral / Low-Value):** Ephemeral stress-test reports (`*-stress-test.md`) for completed/discarded proposals, workarounds for removed libraries, obsolete UI mockups in `docs/mockups/` whose corresponding views have been removed or completely redesigned in production, or trivial low-signal notes.
3. **Interactive Pruning Proposal:**
   - **CRITICAL:** NEVER delete or archive files automatically. Present a table (`File Path`, `Classification`, `Obsolescence Reason`, `Recommended Action`) and await explicit user approval before executing consolidations or deletions.

---

### Section D: Knowledge & ADR Harvesting (Session Learnings Extraction)

1. **Analyze Scope & Diffs:**
   - Default to analyzing unpushed changes or recent commits if no specific scope is provided. Search for complex logic, new design patterns, bug workarounds, and significant architectural decisions.
2. **Apply Longevity & Signal Gating:**
   - Filter out transient trial-and-error logs, routine syntax adjustments, or low-signal one-liners. Only preserve insights with enduring future value:
     - **Decisions:** Why a specific library, schema, or architecture was chosen over alternatives.
     - **Lessons/Gotchas:** Non-trivial bugs, subtle platform edge cases, or tricky configurations.
     - **Patterns:** Reusable architectural conventions introduced in the codebase.
3. **Deduplicate & Persist Upon Approval:**
   - Check `docs/learning/`, `docs/external-references/`, and `docs/adr/` to avoid duplicating existing records.
   - **CRITICAL:** Present extracted learnings/decisions to the user first and request explicit permission before creating files.
   - Once approved, persist architectural decisions as sequential ADRs in `docs/adr/` and high-signal technical lessons in `docs/learning/<topic-slug>.md`. If changes were trivial, report that no persistent learning record was required.

---
**Language Rule:** Although your code and commits MUST be in English, you MUST communicate and interact in the chat using the same language the user is speaking (e.g., Spanish, French, etc.).