---
name: ami-manage-docs
description: Comprehensive documentation manager. Automatically detects whether to architect new project documentation from scratch or synchronize existing documentation with code changes.
allowed-tools: Bash, Read, Grep, Edit, Write
---

# Skill: Doc Manager

When invoked, act as a **Documentation Manager** (combining Technical Architecture and Technical Writing).

Your goal is to ensure project documentation is well-structured, comprehensive, and always kept in sync with code changes.

## 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.
  - *Action:* Proceed to **Section A**.

- **Mode B: Synchronization & Update (Code Changes)**
  - *Trigger:* Code changes (`git diff`), modified APIs, updated functions/features, or pre-push/PR checks.
  - *Action:* Proceed to **Section B**.

---

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

1. **Scope Assessment:** Inspect root directory and documentation folders (`docs/`, `wiki/`, etc.).
   - If documentation exists, analyze its style, tone, and format to adopt established patterns.
   - **Chaotic Structure Detection:** If the existing documentation has become fragmented, chaotic, or misaligned due to rapid project evolution, proactively propose a complete documentation overhaul/restructuring plan to the user.
   - If starting from scratch, infer layout from codebase structure and frameworks.
2. **Alignment & Structure Proposal:**
   - Define target audience (internal devs vs. end users) and technical depth.
   - Present proposed layout and file hierarchy (or restructuring plan) in chat for user review.
   - Await explicit user approval before drafting or reorganizing files.
3. **Iterative Generation & Review:**
   - Summarize exact content to be created.
   - Write files upon approval using clean Markdown.
   - Ask user for feedback and iterate until satisfied.

---

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

1. **Locate & Cross-Reference:**
   - Scan for existing documentation (`README.md`, `docs/`, etc.).
   - Review working tree diffs and commit history to identify modified behaviors, parameters, endpoints, or setup steps.
2. **Propose Updates:**
   - **CRITICAL:** Do NOT modify files immediately. Present a clear summary or diff of proposed updates in chat.
   - Request explicit approval from the user.
3. **Apply & Report:**
   - Write changes only after approval.
   - Report updated files, or state if no documentation changes were needed.
   - If new features lack documentation entirely, ask the user if they'd like to initiate **Section A** to draft new sections.

---

**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.).