jaggerxtrm/documenting

Documenting Skill

This skill provides workflows and tools for maintaining the Serena Single Source of Truth (SSOT) documentation system/memories.

🚨 AGENT GUIDANCE: When to Suggest This Skill

MANDATORY: Suggest or Use this skill in the following scenarios:

✅ Explicit Triggers:

• User asks to "document this", "create memory", "update ssot".
• User asks to "validate documentation", "check metadata".
• User asks to "list memories", "show patterns".
• User asks to "bump version" of a document.

🤖 Autonomous Triggers (End of Task):

• Condition: A task (feature, refactor, bugfix) is completed and verified (tests passed).
• Action: The agent MUST check if SSOT documentation needs creation or update.
• Guideline: "Is this a new component? Update _ssot. Is this a new pattern? Create _pattern. Did I change architecture? Update _ssot."

📋 Detection Pattern:

const shouldDocument = 
  /(document|ssot|memory|metadata|changelog|bump version)/i.test(userMessage) ||
  (taskCompleted && (newFeature || refactor || architectureChange));

---

Core Capabilities

1. Create Memories: Generate new SSOT documents with correct metadata and structure.
2. Update Memories: Bump versions and maintain changelogs.
3. Validate Compliance: Ensure files follow naming conventions and metadata schemas.
4. Navigate: List and find memories by category.

Workflows

🚨 MANDATORY FIRST STEP FOR ALL WORKFLOWS:

Before using ANY Serena tools, activate the project:

mcp__plugin_serena_serena__activate_project({ project: "/path/to/current/working/directory" })

---

Step 1: Detect drift

python3 "$HOME/.claude/skills/documenting/scripts/drift_detector.py" scan

Review the output. If nothing is stale and no explicit documentation request was made → confirm to user and stop.

Step 2: Decide action

| Situation | Action | |---|---| | New feature shipped | Create new SSOT memory OR update existing | | Refactor / architecture change | Update relevant SSOT, bump minor version | | Bug fix only | CHANGELOG entry only (skip memory update unless behaviour changed) | | SKILL.md drift flagged | Update skill + run validate_metadata.py on it |

Step 3: Create or update memory

Creating a new memory:

python3 "$HOME/.claude/skills/documenting/scripts/generate_template.py" \
  ssot <name>_ssot.md title="..." domain="..." subcategory="..."

Fill [PENDING] placeholders. Add tracks: globs pointing to the files this memory documents.

Updating an existing memory:

1. Read the <!-- INDEX --> block only — identify which sections need updating
2. Use search_for_pattern to jump directly to stale sections (avoids reading the full file)
3. Bump version: (patch = content fix, minor = new section, major = full rewrite)
4. Update updated: timestamp to today

Step 4: Regenerate INDEX

python3 "$HOME/.claude/skills/documenting/scripts/validate_metadata.py" <memory-file>

This regenerates the <!-- INDEX --> block automatically from the current ## headings.

Step 5: Update CHANGELOG

python3 "$HOME/.claude/skills/documenting/scripts/changelog/add_entry.py" \
  <changelog_file> <type> "<summary>"

<changelog_file>: path to target CHANGELOG.md (e.g. CHANGELOG.md or .serena/memories/CHANGELOG.md)

Types: Added, Changed, Fixed, Removed.