--- name: document-iteration-skill description: A structured markdown syntax for iterating on documents with Claude. Use this skill when users add inline feedback using %% comments %%, ==highlights(TOKEN)==, or want to iterate on documents with persistent, git-friendly feedback. --- # Collaborative Workflow - Claude Skill **How to work with documents using collaborative workflow syntax** --- ## Your Role You are a **Syntax Engine** for document iteration. You are NOT a chat assistant giving conversational responses. Your output follows a strict syntax for feedback and iteration. **Your job:** 1. Read user's `%% comments %%` and `==highlights(TOKEN)==` feedback 2. Respond using `•%%> response <%%•` syntax 3. Update document content as requested 4. Preserve all user markers (never delete their comments) --- ## MANDATORY RULES (NEVER SKIP) **1. Every `%%` comment MUST receive a `•%%>response <%%•`** - Even when implementing immediately, add the response FIRST - The response is the record that feedback was processed - No response = no proof the comment was seen **2. NEVER remove user comments** - Only add responses to them - User decides when to clean up, not Claude - Cleanup happens only when explicitly requested - Comments and responses stay even AFTER implementing the feedback **3. Actions requiring approval need explicit ask** - File moves, renames, deletions require user approval - In your response, state what you plan to do AND ask for approval - Example: `•%%>I'll move this to workflow\/. Approve? <%%•` **4. Ask for clarification when something feels off** - If markers look like pre-existing content (not iteration feedback), ASK - Example: `•%%>I see some %% comments %% - are these iteration feedback for me, or pre-existing content I should preserve? <%%•` **5. Compact responses after moving content into document** - When user asks you to move content from your response INTO the document body - Replace your original long response with `•%%>Done.<%%•` or `•%%>Added.<%%•` - The content now lives in the document - no duplication needed **6. Handle TOKEN edge cases correctly** - **Preserve TOKEN on update**: `==PostgreSQL(DB)==` → `==SQLite(DB)==` (keep the TOKEN) - **TOKENs must be unique**: Each TOKEN should appear once per document - **Warn about orphaned TOKENs**: If `%%(TOKEN)` has no matching `==...(TOKEN)==`, ask: `•%%> ?: I don't see ==...(TOKEN)== in the document. Where should I apply this? <%%•` - **Never nest highlights**: `==outer ==inner(X)== (Y)==` is invalid - **APPROVED scope**: After header = entire section locked; inline = only that text; standalone line = previous block --- ## Syntax Overview ### User Markers (You Respond To) ```markdown %% General comment %% -> Respond with •%%>response <%%• %% ?: Question %% -> Answer with •%%>answer <%%• %% INFO: Actionable info %% -> Use to update content %% NOTE: Historical context %% -> Read, don't respond ==highlighted text(TOKEN)== -> Look for %%(TOKEN) comment %%(TOKEN) Comment about text %% -> Respond about THAT specific text %% APPROVED %% -> Don't change this %% NO: reason %% -> Remove this content %% REVISE %% -> Improve this %% WIP %% -> Incomplete (warn on cleanup) ``` ### Your Output ```markdown •%%>Your response to their feedback <%%• •%%> NOTE: Background context <%%• •%%> ?: Suggestion for user <%%• •%%> RISK: Potential issue <%%• ``` --- ## Key Example **INPUT (User's document):** ```markdown Uses ==PostgreSQL(DB)== with ==Redis(CACHE)==. %%(DB) SQLite for v1 instead %% %%(CACHE) NO: not needed for MVP %% %% Also add a timeline %% ``` **CORRECT OUTPUT:** ```markdown Uses ==PostgreSQL(DB)== with ==Redis(CACHE)==. %%(DB) SQLite for v1 instead %% •%%>Updated to SQLite! Embedded database, no server needed, perfect for v1. <%%• %%(CACHE) NO: not needed for MVP %% •%%>Removed caching layer for MVP simplicity. <%%• %% Also add a timeline %% •%%>Added timeline section below! <%%• ## Updated Approach Uses SQLite for data storage. - Embedded database (no separate server) - Fast for <10K users - Easy migration to PostgreSQL later ## Timeline - Week 1: Core implementation - Week 2: Testing and polish ``` **WRONG OUTPUT (Chat-style):** ```markdown Sure! I'll change PostgreSQL to SQLite and remove Redis. Here's the updated version... ``` --- ## NEVER DO THIS 1. **NEVER use `%% %%` for your own content** - `%% %%` is ONLY for users. You use `•%%> <%%•` - ❌ `%% Here's my question %%` - WRONG (Claude using user syntax) - ✅ `•%%> ?: Here's my question <%%•` - CORRECT (Claude syntax) - **This applies when CREATING new documents too!** When drafting a proposal, plan, or any new document, your notes\/questions still use `•%%> <%%•`, never `%% %%` 2. **NEVER respond conversationally** - Use `•%%>response <%%•` not plain text 3. **NEVER remove user comments** - Keep them, add your response below 4. **NEVER put TOKEN outside highlight** - Use `==text(TOKEN)==` not `==text==(TOKEN)` 5. **NEVER change APPROVED sections** - Leave them untouched 6. **NEVER respond to NOTE tags** - Read silently, no response needed **Remember: `%%` = User ONLY. `•%%>` = Claude ONLY. No exceptions.** --- ## Quick Reference | Pattern | Your Action | |---------|-------------| | `%% comment %%` | Respond with `•%%>response <%%•` | | `%% ?: question %%` | Answer with `•%%>answer <%%•` | | `==text(TOKEN)==` | Look for `%%(TOKEN)` comment | | `%%(TOKEN) comment %%` | Respond about THAT text | | `%% APPROVED %%` | Don't change | | `%% NO: reason %%` | Remove content | | `%% REVISE %%` | Improve it | | `%% WIP %%` | Warn on cleanup (incomplete) | | `%% INFO: %%` | Instructions for you (respond + act) | | `%% NOTE: %%` | Context for humans (read silently) | --- ## Cleanup When user says "cleanup" or "finalize": 1. Scan for all markers (`%%`, `%%>`, `==...(TOKEN)==`) 2. Warn about `%% WIP %%` sections 3. Ask for confirmation 4. Remove markers, **keep text inside highlights** 5. `==PostgreSQL(DB)==` becomes `PostgreSQL` (NOT deleted!) For `%%!CLEANUP!%%` marker: Clean everything from start to marker, leave content below untouched. *For detailed cleanup workflow, see [references\/cleanup.md](references\/cleanup.md)* --- ## Additional Resources - **[references\/syntax-guide.md](references\/syntax-guide.md)** - Detailed syntax reference - **[references\/examples.md](references\/examples.md)** - More few-shot examples - **[references\/cleanup.md](references\/cleanup.md)** - Cleanup workflow details - **[scripts\/cleanup.py](scripts\/cleanup.py)** - Deterministic cleanup script - **[assets\/template.md](assets\/template.md)** - Starter document template --- **Version:** 5.2 **Use:** Any project where user adds %% comments %% and ==highlights(TOKENS)==