feature-fmt-check

Feature Format Check Skill

This skill validates that feature documentation format follows the established patterns in docs/code/feature-docs.md.

When to Use This Skill

Use this skill when:

• Reviewing a PR that includes feature doc changes
• After creating or editing a feature doc
• Before committing changes to docs/features/
• User requests a feature doc format review

Review Process

Step 1: Identify Changed Feature Docs

For recent commits:

git diff --name-only HEAD~1 | grep 'docs/features/.*\.md$'

For staged changes:

git diff --cached --name-only | grep 'docs/features/.*\.md$'

For unstaged changes:

git diff --name-only | grep 'docs/features/.*\.md$'

Step 2: Validate Each Feature Doc

For each changed feature doc, verify:

1. Frontmatter format
2. Content structure
3. Discovery compatibility

Format Reference

All format requirements are defined in docs/code/feature-docs.md. Read that file for:

• Frontmatter field requirements (name, description, components)
• Description guidelines (third person, "Load when" triggers, no ending period)
• Component prefix rules (crate:, service:, app:)
• Required and optional sections (Summary, Key Concepts, Architecture, Usage, etc.)
• Reference direction rules (references flow UP the hierarchy)
• No empty sections rule

Use the Checklist section in docs/code/feature-docs.md to validate feature docs.

Discovery Validation

Verify frontmatter is extractable:

Primary Method: Use the Grep tool with multiline mode:

• Pattern: ^---\n[\s\S]*?\n---
• Path: docs/features/<feature-name>.md
• multiline: true
• output_mode: content

Fallback: Bash command:

grep -Pzo '(?s)^---\n.*?\n---' docs/features/<feature-name>.md

Cross-platform alternative (macOS compatible):

awk '/^---$/{p=!p; print; next} p' docs/features/<feature-name>.md

Validation Process

1. Identify changed files: git diff --name-only HEAD~1 | grep 'docs/features/.*\.md$'
2. Read the feature doc and Read docs/code/feature-docs.md
3. Validate using the checklist in the patterns file
4. Report findings using format below

Review Report Format

After validation, provide a structured report listing issues found. Use the checklist from docs/code/feature-docs.md as the validation criteria.

## Feature Doc Format Review: <filename>

### Issues Found
1. <issue description with line number>
2. <issue description with line number>

### Verdict: PASS/FAIL

<If FAIL, provide specific fixes needed referencing docs/code/feature-docs.md>

Common Issues

When validation fails, refer to docs/code/feature-docs.md for detailed requirements. Common issues include:

• Invalid frontmatter YAML syntax
• name not in kebab-case or doesn't match filename
• description has ending period or missing "Load when" trigger
• components missing required prefixes (crate:, service:, app:)
• Wrong section names (e.g., Overview instead of Summary)
• Missing required sections or empty optional sections
• References linking downward (violates "flow UP" rule)

Pre-approved Commands

These tools/commands can run without user permission:

• Discovery command (Grep tool or bash fallback) on docs/features/
• All git diff and git status read-only commands
• Reading files via Read tool

Next Steps

After format review:

1. If format issues found - List specific fixes needed
2. If format passes - Approve for commit