troykelly/features-documentation

Features Documentation Enforcement

Overview

Ensures all user-facing feature changes are reflected in features documentation. When documentation drift is detected, work pauses until documentation is synchronized.

Core principle: Users must be able to discover and understand all features. Undocumented features don't exist to users.

Announce at start: "I'm using features-documentation to verify feature documentation sync."

When This Skill Triggers

This skill is triggered when changes affect user-facing functionality:

| Change Type | Examples | Trigger Reason | |-------------|----------|----------------| | New feature | New button, page, capability | Must be documented | | Feature modification | Changed behavior, new options | Docs must reflect current state | | Feature removal | Deprecated/removed capability | Remove from docs | | UI changes | New flows, changed interactions | User guidance needed | | Configuration | New settings, options | Users need to know options |

Documentation Locations

Check these locations for features documentation:

| File | Purpose | |------|---------| | docs/features.md | Primary features documentation | | docs/FEATURES.md | Alternative location | | FEATURES.md | Root-level features doc | | docs/user-guide.md | User-facing guide | | docs/guide.md | Usage guide | | README.md (Features section) | Embedded features list |

The Protocol

Step 1: Detect Feature Changes

# Check if current changes affect user-facing features
FEATURE_CHANGED=false

# UI components
if git diff --name-only HEAD~1 | grep -qE "(components/|pages/|views/|screens/)"; then
  FEATURE_CHANGED=true
fi

# Feature flags
if git diff --name-only HEAD~1 | grep -qE "(features\.|feature-flags|config/)"; then
  FEATURE_CHANGED=true
fi

# Configuration/settings
if git diff --name-only HEAD~1 | grep -qE "(settings|preferences|config)"; then
  FEATURE_CHANGED=true
fi

echo "Feature Changed: $FEATURE_CHANGED"

Step 2: Find Documentation File

find_feature_docs() {
  for file in docs/features.md docs/FEATURES.md FEATURES.md \
              docs/user-guide.md docs/guide.md; do
    if [ -f "$file" ]; then
      echo "$file"
      return 0
    fi
  done

  # Check README for Features section
  if [ -f "README.md" ] && grep -q "## Features" README.md; then
    echo "README.md"
    return 0
  fi

  return 1
}

DOC_FILE=$(find_feature_docs)
if [ -z "$DOC_FILE" ]; then
  echo "WARNING: No features documentation file found"
  echo "PAUSE: Trigger documentation-audit skill to create"
fi

Step 3: Verify Feature Coverage

verify_feature_coverage() {
  local doc_file=$1
  local issues_found=false

  # Extract feature names from code (common patterns)
  CODE_FEATURES=$(find . -name "*.ts" -name "*.tsx" \
    -exec grep -h "feature:" {} \; 2>/dev/null | \
    sed 's/.*feature:\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' | sort -u)

  # Extract documented features
  DOC_FEATURES=$(grep -oP '(?<=^## |^### |^\* \*\*)[^*]+(?=\*\*|$)' "$doc_file" | \
    tr '[:upper:]' '[:lower:]' | sort -u)

  # Find undocumented features
  for feature in $CODE_FEATURES; do
    feature_lower=$(echo "$feature" | tr '[:upper:]' '[:lower:]')
    if ! echo "$DOC_FEATURES" | grep -q "$feature_lower"; then
      echo "UNDOCUMENTED: $feature"
      issues_found=true
    fi
  done

  if [ "$issues_found" = "true" ]; then
    return 1
  fi
  return 0
}

Step 4: Handle Drift

If documentation drift is detected:

## Features Documentation Drift Detected

**Status:** PAUSED
**Reason:** Features documentation is out of sync with code

### Undocumented Features
- **Dark Mode** (added in `components/ThemeToggle.tsx`)
- **Export to PDF** (added in `features/export/`)
- **Multi-language Support** (added in `i18n/`)

### Action Required
1. Invoke `documentation-audit` skill
2. Update features documentation
3. Resume current work after sync complete

---
*features-documentation skill paused work*

Then invoke documentation-audit:

Use Skill tool: documentation-audit

Documentation Requirements

When updating features documentation, include:

Required for Each Feature

| Section | Description | |---------|-------------| | Name | Clear, user-friendly name | | Description | What it does, why it's useful | | How to Use | Step-by-step instructions | | Prerequisites | Requirements, permissions | | Configuration | Available options/settings | | Examples | Common use cases | | Limitations | Known constraints |

Example Feature Entry

## Dark Mode

Switch between light and dark color themes for comfortable viewing in any lighting condition.

### How to Use

1. Click the **Settings** icon in the top navigation
2. Select **Appearance**
3. Choose your preferred theme:
   - **Light** - Best for bright environments
   - **Dark** - Reduces eye strain in low light
   - **System** - Follows your OS preference

### Configuration

| Setting | Options | Default |
|---------|---------|---------|
| Theme | Light, Dark, System | System |
| Transition | Instant, Animated | Animated |

### Keyboard Shortcut

Press `Ctrl+Shift+T` (Windows/Linux) or `Cmd+Shift+T` (Mac) to toggle.

### Notes

- Theme preference is saved to your account
- Some third-party embeds may not respect dark mode

Features Document Structure

# Features

## Overview
Brief description of the product and its core purpose.

## Core Features

### [Feature 1 Name]
[Feature 1 content]

### [Feature 2 Name]
[Feature 2 content]

## Advanced Features

### [Feature 3 Name]
[Feature 3 content]

## Experimental Features

### [Beta Feature Name]
[Beta feature content with experimental warning]

## Deprecated Features

### [Deprecated Feature]
[Migration guidance]

---
*Last updated: [DATE]*

Validation

After updating documentation:

# Check markdown validity
npx markdownlint docs/features.md

# Check for broken links
npx markdown-link-check docs/features.md

# Check all features have required sections
grep -c "^### How to Use" docs/features.md

Checklist

Before resuming work:

• [ ] Features documentation file exists
• [ ] All user-facing features documented
• [ ] How-to-use instructions provided
• [ ] Configuration options listed
• [ ] Examples included
• [ ] Deprecated features marked
• [ ] Documentation validates
• [ ] Changes committed

Integration

This skill coordinates with:

| Skill | Purpose | |-------|---------| | documentation-audit | Full documentation sync | | issue-driven-development | Triggered during implementation | | comprehensive-review | Validates documentation complete |

When to Skip

This skill can be skipped when:

• Changes are purely internal (no user-visible impact)
• Changes are to backend/infrastructure only
• Changes are to test files only
• Changes are to documentation itself
• Project is a library without UI