From for-the-record
Capture structured documentation from conversation context - decisions, technical references, discussion summaries, how-to guides, and architecture docs. Auto-structures content, generates tags, and writes to .things/ for search and cross-reference.
How this skill is triggered — by the user, by Claude, or both
Slash command
/for-the-record:add-doc-ftrThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<purpose>
<load-config>
<action>Resolve the user's home directory.</action>
<command language="bash" output="home" tool="Bash">echo $HOME</command>
<constraint>Never pass `~` to the Read tool.</constraint>
<read path="<home>/.things/config.json" output="config" />
<if condition="config-missing">Tell the user: "Run `/things:setup-things` first." Then stop.<exit /></if>
<read path="<home>/.things/for-the-record/preferences.json" output="preferences" />
<if condition="preferences-missing">Tell the user: "Run `/setup-ftr` first." Then stop.<exit /></if>
</load-config>
Parse Arguments
<action>Parse `$ARGUMENTS` for:</action>
- **topic**: The subject to document (everything that isn't a flag)
- **--detailed**: Override detail level to `detailed`
- **--tags tag1,tag2**: Explicit tags to include (comma-separated)
<action>Set `detail_level` from `--detailed` flag or fall back to `preferences.default_detail_level`.</action>
Gather Context from Conversation
<action>Search the conversation history for content relevant to the topic. Scope to the topic if one was provided.</action>
<constraint>
What counts as documentable context:
- Technical discussions, decisions, architecture plans
- Problem-solving sessions with conclusions
- How-to walkthroughs or setup procedures
- Design evaluations with tradeoffs
- Configuration or integration details
- Explanations of systems, patterns, or approaches
</constraint>
<if condition="no-useful-context">
<ask-user-question>
<question>I don't see relevant context in our conversation for "{topic}". What would you like to document?</question>
</ask-user-question>
</if>
<if condition="topic-not-provided-and-context-ambiguous">
<ask-user-question>
<question>What would you like to capture as a document? I can see a few threads in our conversation.</question>
</ask-user-question>
</if>
Choose Document Structure
<action>Based on the gathered context, auto-choose the best document structure:</action>
| Content Pattern | Structure |
|----------------|-----------|
| Weighed options, chose an approach | Decision Doc: Context → Options → Evaluation → Decision → Rationale |
| Explained a system, API, or tool | Technical Reference: Overview → Details → Usage → Caveats |
| Discussed a topic, reached conclusions | Discussion Summary: Topic → Key Points → Conclusions → Open Questions |
| Walked through steps to accomplish something | How-To Guide: Goal → Prerequisites → Steps → Verification |
| Designed a system or component | Architecture Doc: Overview → Components → Data Flow → Constraints |
<constraint>If the content doesn't clearly fit one structure, pick the closest match. Don't ask the user to choose — the auto-selection should be good enough. If genuinely ambiguous between two, briefly mention which you chose and why.</constraint>
Compose the Document
<action>Write the document body using the chosen structure.</action>
<constraint>
Detail level controls depth:
- **concise**: Key points, decisions, outcomes. 1-2 paragraphs per section. Code blocks only when essential. Strip tangential discussion.
- **detailed**: Full reasoning chains, all alternatives discussed, complete code blocks, edge cases, caveats, and context that future-you needs. Preserve the richness of the conversation.
</constraint>
<constraint>Preserve specificity. "Configured app's prompt routing to use XML workflow tags" is better than "set up the system." Capture project names, tool names, version numbers, file paths, and configuration details.</constraint>
Generate Tags
<if condition="preferences.auto_tag == true">
<action>Auto-generate tags by combining:</action>
- Technologies and tools mentioned (e.g., `rust`, `python`, `claude-code`)
- Domain keywords (e.g., `architecture`, `security`, `performance`)
- Activity type (e.g., `decision`, `reference`, `how-to`)
- Project names mentioned
- Any explicit `--tags` from arguments
<action>Read existing `<home>/.things/for-the-record/tags.json` and cross-reference for consistency. Prefer existing tag spellings over new variations (e.g., use `claude-code` if it exists rather than creating `claude_code`).</action>
<action>Also check `<home>/.things/tags/index.json` (central tag index) for cross-plugin tag consistency.</action>
</if>
<if condition="preferences.auto_tag == false">
<action>Use only explicit `--tags` from arguments. If none provided, ask.</action>
</if>
<ask-user-question>
<question>Here are the generated tags for this document. Add, remove, or modify:</question>
<option>Looks good</option>
<option-with-text-input>Make changes</option-with-text-input>
</ask-user-question>
Generate Filename
<action>Generate filename: `<YYYY-MM-DD>-<slugified-topic>.md`</action>
<constraint>Slugify: lowercase, replace spaces and special chars with hyphens, collapse multiple hyphens, trim to reasonable length (~60 chars max for the slug portion).</constraint>
<action>Check if file already exists at `<home>/.things/for-the-record/docs/<filename>`.</action>
<if condition="file-exists">
<ask-user-question>
<question>A document with this name already exists. What would you like to do?</question>
<option>Replace it</option>
<option-with-text-input>Use a different name</option-with-text-input>
</ask-user-question>
</if>
Write Document
<write path="<home>/.things/for-the-record/docs/<filename>">
<constraint>Use the frontmatter schema from `references/doc-format.md`.</constraint>
<template name="document">
```markdown
---
title: "<title>"
date: <YYYY-MM-DD>
description: "<1-2 sentence summary>"
detail_level: "<concise|detailed>"
source_type: "conversation"
tags: [<tags>]
---
<document body using chosen structure>
```
</template>
</write>
Rebuild Index
<constraint>The things PostToolUse hook automatically dispatches `rebuild-index.py` via the registry after writing a doc file. No manual rebuild needed.</constraint>
<if condition="hook-did-not-fire">The rebuild can be run manually:
<command language="bash" tool="Bash">python3 <plugin_root>/scripts/rebuild-index.py $HOME/.things</command>
</if>
Handle Git Workflow
<git-workflow>
<action>Pull latest before committing.</action>
<command language="bash" tool="Bash">git -C <home>/.things pull --rebase 2>/dev/null || true</command>
<action>Read git workflow from `config.json` (`git.workflow`).</action>
<if condition="workflow-auto">Automatically `git add`, `git commit -m "doc: <title>"`, and `git push`.</if>
<if condition="workflow-ask">
<ask-user-question>
<question>Commit and push this document?</question>
<option>Yes -- commit and push</option>
<option>Commit only</option>
<option>No -- I'll handle git myself</option>
</ask-user-question>
</if>
<if condition="workflow-manual">Tell the user the file has been saved.</if>
</git-workflow>
Confirm
<completion-message>
Captured: **<title>** (`<detail_level>`, `<structure_type>`)
Location: `<home>/.things/for-the-record/docs/<filename>`
Tags: `<tags>`
Find it later: `/things:search-things --tag <tag>` or `/things:search-things <keyword>`
</completion-message>
npx claudepluginhub brennacodes/brenna-plugs --plugin for-the-recordCaptures decisions, conventions, patterns, issues, and concepts from conversations into docs/ markdown nodes using triage output. Auto-activates on save intents or decision signals.
Captures team discussions, meeting notes, and conversations into structured Markdown files with participants, key points, decisions, action items, and updates monthly YAML indexes.
Captures solved problems, bug fixes, and learnings from conversations into structured markdown files in docs/learnings/. Auto-invokes after 'that worked', 'it's fixed', etc., or via /learn.