--- name: agenticnotetaking/help source: https://app.decimal.ai/s/agenticnotetaking-help@1/SKILL.md source_sha256: cb4f5ad863bc --- ## EXECUTE NOW **Target: $ARGUMENTS** Parse immediately: - If target contains `--compact`: force compact mode regardless of vault state - If target contains a skill name (e.g., "help reduce" or "help reflect"): show detailed help for that specific skill - If target is empty: determine mode from vault state **Execute these steps:** 1. Gather vault state (Step 1) 2. Resolve domain vocabulary (Step 2) 3. Determine mode (Step 3) 4. Discover commands dynamically (Step 4) 5. Render the appropriate mode (Step 5) **START NOW.** Reference below defines each step. --- ## Step 1: Gather Vault State Determine the **notes folder** by checking which domain-named directory exists (notes/, reflections/, concepts/, ideas/, decisions/, memories/, or any custom name from derivation-manifest.md). Then gather counts: - **Note count:** `.md` files in the notes folder, excluding MOCs (files with `type: moc` in frontmatter) - **Inbox count:** `.md` files in the inbox folder (inbox/, journal/, encounters/, etc.) - **Observation count:** `.md` files in `ops/observations/` or `ops/methodology/` - **Tension count:** `.md` files in `ops/tensions/` - **Connection density:** count wiki links (`[[`) across notes folder; sparse if fewer than 2x note count - **Queue state:** pending tasks in `ops/queue/queue.yaml` or `ops/queue/queue.json` - **Health warnings:** check latest report in `ops/health/` if it exists - **Tutorial state:** check `ops/tutorial-state.yaml` for incomplete tutorial - **Session count:** estimate from `ops/sessions/` file count (indicates usage maturity) ```bash # Quick state gathering note_count=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ') inbox_count=$(ls -1 {vocabulary.inbox}/*.md 2>/dev/null | wc -l | tr -d ' ') obs_count=$(ls -1 ops/observations/*.md ops/methodology/*.md 2>/dev/null | wc -l | tr -d ' ') tension_count=$(ls -1 ops/tensions/*.md 2>/dev/null | wc -l | tr -d ' ') ``` ## Step 2: Resolve Domain Vocabulary Read `ops/derivation-manifest.md` (or fall back to `ops/derivation.md` Vocabulary Mapping section). Extract domain-native names for: reduce, reflect, reweave, verify, rethink, note, MOC, inbox. If neither file exists, use universal names. For display, show domain name with universal in parentheses when they differ: ``` /{domain:reduce} (reduce) Extract patterns from journal entries ``` If domain name equals universal name, show just the name: ``` /reduce Extract insights from source material ``` ## Step 3: Determine Mode | Condition | Mode | |-----------|------| | `--compact` in arguments | Compact | | Specific skill name in arguments | Skill detail | | Note count < 5 | Narrative | | Note count >= 5 | Contextual | ## Step 4: Discover Commands Scan `${CLAUDE_PLUGIN_ROOT}/skills/` dynamically: - Subdirectories containing `SKILL.md` (e.g., `reduce/SKILL.md`) Extract `name:` and `description:` from each frontmatter. Do NOT hardcode the command list. **Command categories:** | Category | Commands | When to Show | |----------|----------|-------------| | Core | /ask, /learn, /next, /help | Always | | Processing | /reduce, /reflect, /reweave, /verify | Always (all skills from day one) | | Maintenance | /health, /rethink, /remember | Always | | Evolution | /architect, /reseed, /add-domain, /upgrade | Always | | Meta | /tutorial, /graph, /stats | Always | ## Step 5: Render ### NARRATIVE MODE (note count < 5) This is the first impression. The user is new or nearly new. Explain what the system IS before listing what it DOES. **What narrative mode communicates:** 1. What Ars Contexta is (one sentence) 2. What THEIR system was built to do (read from ops/derivation.md if available) 3. What they can do RIGHT NOW (concrete actions, not abstract possibilities) 4. How the system grows with them ``` --=={ ars contexta : help }==-- Your knowledge system is ready. It turns thoughts into a connected graph where every note compounds the value of every other note. [If ops/derivation.md exists:] Your system: [domain description from derivation] Getting started: Tell me a thought, observation, or question. I will turn it into a note and show you what the system does with it. Or try one of these: /ask [question] Ask about [domain] -- I will answer from your graph /learn [topic] Research [topic] and grow your graph with findings /tutorial Walk through the system step by step (5 minutes) As your graph grows, you will use: /reduce [source] Extract insights from articles, notes, or any raw material /reflect Find connections between notes /health Check your system's health Your system also learns from experience: /remember Capture when something goes wrong (your system remembers corrections) /ask [question] Ask about [domain] -- answers draw from 249 methodology notes AND your system's own methodology notes Type /help anytime for guidance. ``` **Manual reference (if manual/ exists):** If the vault contains a `manual/` directory, add to the narrative output: ``` For a deeper guide, read manual/getting-started.md or explore the full manual in manual/manual.md. ``` **Key principles for narrative mode:** - Conversational, not list-like - Show the easiest entry point first ("tell me a thought") - Group commands by when the user would need them, not alphabetically - Reference the user's actual domain when possible - If tutorial is incomplete, mention: "You have an unfinished tutorial (step N of 5). Resume with /tutorial" ### CONTEXTUAL MODE (note count >= 5) The user has been working. Show them what is happening NOW and what would be most valuable NEXT. **What contextual mode communicates:** 1. Current system state (brief metrics) 2. What needs attention right now (state-aware) 3. Suggested next action (the single most valuable thing) 4. Commands they might not know yet 5. Full command reference ``` --=={ ars contexta : help }==-- Your system: [domain] knowledge graph [N] notes, [M] connections, [P] pending tasks Right now: [State-aware observations — pick up to 3 most relevant:] Your inbox has [N] items (oldest: [age]) [N] pending observations -- approaching /rethink threshold Pipeline: [N] tasks at [phase] phase [N] notes have sparse connections (< 2 links) Suggested: [Single most valuable next action with rationale] [If user hasn't tried certain commands:] Commands you might not know: /remember Capture when something goes wrong (teaches your system from friction) /graph Explore your knowledge graph visually /stats See vault metrics in shareable format All commands: /ask [question] Query your knowledge system /learn [topic] Research and grow your graph /next Next recommended action /{reduce} [source] Extract insights from material /{reflect} Find connections between notes /{reweave} Update older notes /verify [note] Combined quality verification /health Run vault diagnostics /{rethink} Challenge assumptions /remember Capture methodology learning /architect Research-backed evolution advice /reseed Principled restructuring /add-domain Extend with a new domain /upgrade Check for skill improvements /tutorial Interactive walkthrough /graph Graph exploration /stats Vault metrics ``` **State-aware suggestion logic:** Pick the FIRST matching condition: | Condition | Suggestion | |-----------|-----------| | Inbox has items | `Process your inbox: /{reduce} [oldest-inbox-item-filename]` | | Pipeline has pending tasks | `Resume processing: /next` | | 10+ observations or 5+ tensions | `Review accumulated evidence: /{rethink}` | | Health warnings exist | `Check health: /health` | | Notes exist, sparse connections | `Build connections: /{reflect}` | | User hasn't tried /learn | `Grow your graph: /learn [topic related to their domain]` | | Methodology folder has friction notes | `Your system is learning from friction -- review with /{rethink}` | | Methodology folder has notes beyond derivation-rationale | `Your system has [N] operational learnings -- query them with /ask or browse ops/methodology/` | | Sessions accumulating without mining | `Mine session learnings: /remember` | | Healthy vault, no pressure | `What is next: /next` | Reference a specific file when possible (e.g., the actual oldest inbox filename, the actual pending task description). **Manual page suggestion (if manual/ exists):** Based on the first matching state-aware condition, suggest the relevant manual page: | Condition | Manual Page | |-----------|------------| | Inbox has items | [[workflows]] (processing pipeline) | | Pipeline has pending tasks | [[workflows]] (batch processing) | | Observations/tensions accumulated | [[meta-skills]] (/rethink guide) | | Health warnings exist | [[troubleshooting]] | | Sparse connections | [[workflows]] (connection finding) | | General orientation needed | [[getting-started]] | Add: `For details, see manual/{page}.md` **"Commands you might not know" logic:** Track which commands the user has likely used by checking for their artifacts: - /learn used if `ops/sessions/` has learn-related transcripts or inbox has research files - /remember used if `ops/methodology/` or `ops/observations/` has files - /graph used if... (no artifact, always suggest if note count > 20) - /stats used if... (no artifact, always suggest if note count > 10) Show up to 3 commands the user probably has not tried. Skip commands they clearly have used. ### COMPACT MODE (--compact flag) Quick reference. No state analysis. No suggestions. Just the commands. ``` --=={ ars contexta : help --compact }==-- /ask [question] Query knowledge system /learn [topic] Research and grow graph /next Next recommended action /{reduce} [source] Extract insights /{reflect} Find connections /{reweave} Update older notes /verify [note] Quality verification /health Vault diagnostics /{rethink} Challenge assumptions /remember Capture methodology learning /architect Evolution advice /reseed Restructure system /add-domain Add new domain /upgrade Check for improvements /tutorial Interactive walkthrough /graph Graph exploration /stats Vault metrics /help This guide ``` ### SKILL DETAIL MODE (help [skill-name]) When the user asks for help with a specific skill (e.g., `/help reduce` or `/help reflect`): 1. Find the skill's SKILL.md file 2. Read its frontmatter (name, description) and first section 3. Display a focused guide: ``` --=={ ars contexta : help /{skill-name} }==-- {Description from frontmatter} Usage: /{skill-name} [arguments] Examples: /{skill-name} inbox/article.md /{skill-name} --since 7d What it does: {2-3 sentence summary extracted from the skill's philosophy or first methodology section} Related: /{related-skill} {one-line description} ``` **Special case for /help ask:** Expand the "What it does" section to mention both knowledge layers: ``` What it does: Queries the bundled methodology knowledge base (249 research claims) AND your local methodology notes in ops/methodology/. Answers are grounded in specific claims and applied to your system's configuration. ``` Extract the pipeline position (what comes before and after this skill) to show workflow context. **Manual cross-reference:** If `manual/skills.md` exists, also check it for additional context about the requested skill. The manual may contain domain-specific examples and workflow context that the SKILL.md frontmatter does not include. --- ## Rendering Rules - Max width: 76 characters - No ANSI color codes - No emoji - Monospaced alignment assumed - Display short command forms (`/reduce`), not plugin-qualified forms (`/arscontexta:reduce`) - Domain-native names in curly braces (e.g., `/{reduce}`) are resolved from derivation-manifest.md - When domain name equals universal name, drop the braces ## Edge Cases **No ops/derivation-manifest.md:** Use universal vocabulary for all command names. **Pre-init invocation:** If no vault structure exists at all (no notes folder, no ops/), show a minimal message: ``` Ars Contexta is not initialized in this directory. Run /setup to create your knowledge system. ``` **Multiple domains:** If `ops/derivation-manifest.md` lists multiple domains, show commands grouped by domain in contextual mode.