devflow-kit 0.9.0 → 1.1.0

package/shared/skills/docs-framework/references/violations.md

@@ -0,0 +1,221 @@
+# Documentation Framework Violations
+
+Common violations of documentation conventions with detection patterns and fixes.
+
+---
+
+## Naming Convention Violations
+
+| Violation | Bad Example | Correct Example | Fix |
+|-----------|-------------|-----------------|-----|
+| Wrong timestamp format | `2025-1-5` | `2025-01-05_1430` | Use `YYYY-MM-DD_HHMM` |
+| Missing time in timestamp | `2025-01-05` | `2025-01-05_1430` | Include `_HHMM` suffix |
+| Unsanitized branch slug | `feature/auth` | `feature-auth` | Replace `/` with `-` |
+| Wrong case for artifacts | `Status-2025-01-05.md` | `2025-01-05_1430.md` | Use lowercase except special indexes |
+| Wrong case for indexes | `index.md` | `INDEX.md` | UPPERCASE for special indexes |
+| Files outside .docs | `docs/status.md` | `.docs/status/2025-01-05_1430.md` | Use `.docs/` root |
+| Missing INDEX.md | Status files without index | Create `INDEX.md` | Every directory needs index |
+| Special chars in slug | `oauth-2.0-auth` | `oauth-20-auth` | Strip non-alphanumeric except `-` |
+
+---
+
+## Directory Structure Violations
+
+### Wrong: Flat Structure
+
+```
+project/
+├── status-2025-01-05.md    # Wrong location
+├── review-auth.md          # Missing timestamp, wrong location
+└── catch_up.md             # Wrong case, wrong location
+```
+
+### Wrong: Non-standard Subdirectories
+
+```
+.docs/
+├── logs/                   # Should be status/
+├── reports/                # Should be reviews/{branch-slug}/
+└── notes.md                # Should be in appropriate subdir
+```
+
+---
+
+## Timestamp Violations
+
+### Missing Leading Zeros
+
+```bash
+# WRONG
+date +%Y-%m-%d_%H%M  # Could produce: 2025-1-5_930
+
+# RIGHT
+date +%Y-%m-%d_%H%M  # Always produces: 2025-01-05_0930
+```
+
+Note: `date` command handles padding, but manual timestamps often miss it.
+
+### Wrong Separator
+
+```bash
+# WRONG
+2025-01-05-1430   # Dash instead of underscore
+2025/01/05_1430   # Slash in date
+2025.01.05_1430   # Dot in date
+
+# RIGHT
+2025-01-05_1430   # Underscore separating date from time
+```
+
+---
+
+## Branch Slug Violations
+
+### Unhandled Slash
+
+```bash
+# WRONG - produces invalid filename
+BRANCH_SLUG=$(git branch --show-current)
+# Result: feature/auth -> invalid path
+
+# RIGHT - sanitizes slash
+BRANCH_SLUG=$(git branch --show-current | sed 's/\//-/g')
+# Result: feature/auth -> feature-auth
+```
+
+### Missing Fallback
+
+```bash
+# WRONG - fails in detached HEAD
+BRANCH_SLUG=$(git branch --show-current)
+# Result: empty string -> broken path
+
+# RIGHT - with fallback
+BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
+# Result: (detached HEAD) -> standalone
+```
+
+---
+
+## Topic Slug Violations
+
+### Preserving Special Characters
+
+```bash
+# WRONG - special chars break filenames
+TOPIC="Bug: Can't login (v2.0)"
+SLUG="Bug:-Can't-login-(v2.0)"
+
+# RIGHT - stripped and normalized
+SLUG="bug-cant-login-v20"
+```
+
+### Not Truncating Long Names
+
+```bash
+# WRONG - excessively long filename
+TOPIC="This is a very long topic name that describes the entire feature..."
+SLUG="this-is-a-very-long-topic-name-that-describes-the-entire-feature"
+
+# RIGHT - truncated at 50 chars
+SLUG="this-is-a-very-long-topic-name-that-describes-the"
+```
+
+---
+
+## File Type Violations
+
+### Wrong Case for Special Files
+
+```bash
+# WRONG
+catch_up.md      # Should be CATCH_UP.md
+index.md         # Should be INDEX.md
+knowledge_base.md # Should be KNOWLEDGE_BASE.md
+
+# RIGHT - UPPERCASE for special indexes
+CATCH_UP.md
+INDEX.md
+KNOWLEDGE_BASE.md
+```
+
+### Wrong Case for Artifacts
+
+```bash
+# WRONG
+Status-2025-01-05_1430.md
+Security-Report.md
+
+# RIGHT - lowercase for artifacts
+2025-01-05_1430.md
+security-report.2025-01-05_1430.md
+```
+
+---
+
+## Template Usage Violations
+
+### Missing Required Sections
+
+```markdown
+# WRONG - missing key sections
+
+# Status Update
+
+Did some work today.
+```
+
+```markdown
+# RIGHT - all required sections
+
+# Status Update - 2025-01-05_1430
+
+## Session Summary
+Implemented user authentication feature.
+
+## Branch Context
+- **Branch**: feat/auth
+- **Base**: main
+- **Status**: 3 commits ahead
+
+## Work Completed
+- Added JWT validation middleware
+- Created login endpoint
+
+## Files Changed
+- `src/auth/jwt.ts` - JWT utilities
+- `src/routes/login.ts` - Login endpoint
+
+## Next Steps
+- [ ] Add refresh token support
+- [ ] Write integration tests
+```
+
+---
+
+## Detection Patterns
+
+Use these patterns to find violations:
+
+```bash
+# Find files outside .docs/
+find . -name "*.md" -path "*/docs/*" ! -path "*/.docs/*"
+
+# Find wrong timestamp format (missing underscore)
+grep -r "^\d{4}-\d{2}-\d{2}[^_]" .docs/
+
+# Find lowercase special indexes
+ls .docs/**/index.md .docs/**/catch_up.md 2>/dev/null
+
+# Find uppercase artifacts (excluding special files)
+find .docs -name "*.md" | grep -v "INDEX\|CATCH_UP\|KNOWLEDGE_BASE" | xargs -I {} basename {} | grep "^[A-Z]"
+
+# Find unsanitized branch names in paths
+find .docs/reviews -type d -name "*/*" 2>/dev/null
+```
+
+---
+
+## Quick Reference
+
+For correct patterns and templates, see [patterns.md](patterns.md).

package/shared/skills/documentation-patterns/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: documentation-patterns
+description: Documentation analysis patterns for code review. Detects doc drift from code changes, missing documentation for public APIs, stale comments, and misleading README sections. Loaded by Reviewer agent when focus=documentation.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Documentation Patterns
+
+Domain expertise for documentation quality and alignment. Use alongside `review-methodology` for complete documentation reviews.
+
+## Iron Law
+
+> **DOCUMENTATION MUST MATCH REALITY**
+>
+> Outdated documentation is worse than no documentation. It actively misleads. Every code
+> change that affects behavior requires a documentation check. Comments that explain "what"
+> instead of "why" are noise. The best documentation is code that doesn't need documentation.
+
+---
+
+## Documentation Categories
+
+### 1. Code Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing docstrings | Complex functions without explanation | Add JSDoc with params, returns, throws |
+| Outdated comments | Comments that contradict code | Update or remove |
+| "What" comments | `// Loop through users` | Explain "why" instead |
+| Magic algorithms | Complex logic without explanation | Document algorithm and rationale |
+
+**Brief Example - Missing vs. Complete:**
+```typescript
+// BAD: No documentation on complex function
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+
+// GOOD: Purpose, params, returns, edge cases documented
+/**
+ * Calculates prorated billing amount when switching plans mid-cycle.
+ * @param plan - The new plan to prorate to
+ * @returns Prorated amount in cents (can be negative for downgrades)
+ */
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+```
+
+### 2. API Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing params | Callers don't know valid values | Document all params with types and constraints |
+| Missing returns | Return shape unknown | Describe return structure and units |
+| Missing errors | Callers don't know what to catch | List all thrown error types |
+
+**Brief Example - Incomplete vs. Complete:**
+```typescript
+// BAD: No params, no errors documented
+/** Creates a subscription. */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+
+// GOOD: Full contract documented
+/**
+ * @param userId - User's unique identifier
+ * @param planId - Plan ID from /plans endpoint
+ * @throws {UserNotFoundError} If userId doesn't exist
+ * @throws {PlanNotFoundError} If planId doesn't exist
+ */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+```
+
+### 3. Alignment Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Code-comment drift | Comment says 3 retries, code does 5 | Update comment or use constant |
+| Stale README | Examples use removed functions | Keep README in sync with code |
+| Missing changelog | Breaking changes undocumented | Document all notable changes |
+
+**Brief Example - Drift vs. Aligned:**
+```typescript
+// BAD: Comment doesn't match code
+// Retries up to 3 times
+for (let i = 0; i < 5; i++) { /* ... */ }
+
+// GOOD: Use constant to keep aligned
+const MAX_RETRIES = 5;
+for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands:
+
+- **[references/violations.md](references/violations.md)** - Extended violation examples with explanations
+- **[references/patterns.md](references/patterns.md)** - Complete correct pattern examples
+- **[references/detection.md](references/detection.md)** - Bash commands for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **CRITICAL** | Actively misleading | Comments contradict code; API docs with wrong types; README with broken steps; Changelog missing breaking changes |
+| **HIGH** | Significant gaps | Public APIs undocumented; Complex algorithms unexplained; Errors not documented; Migration guides missing |
+| **MEDIUM** | Moderate issues | Some params undocumented; Examples could be clearer; "What" comments instead of "why" |
+| **LOW** | Minor improvements | Could add more examples; Formatting inconsistencies; Typos |
+
+---
+
+## Documentation Checklist
+
+Before approving changes:
+
+- [ ] All public APIs have JSDoc/docstrings
+- [ ] Parameters and return values documented
+- [ ] Error conditions documented
+- [ ] Complex algorithms explained
+- [ ] Comments explain "why", not "what"
+- [ ] README reflects current state
+- [ ] CHANGELOG updated for notable changes
+- [ ] No TODO comments for completed work
+- [ ] Examples work with current API

package/shared/skills/documentation-patterns/references/detection.md

@@ -0,0 +1,190 @@
+# Documentation Detection Patterns
+
+Bash commands and search patterns for finding documentation issues.
+
+---
+
+## Finding Missing Documentation
+
+### Functions Without JSDoc
+
+```bash
+# Find exported functions without JSDoc comment above
+grep -rn "export function\|export async function" --include="*.ts" | \
+  xargs -I {} sh -c 'grep -B1 "{}" | grep -v "/\*\*"'
+
+# Find all exports, check for docs
+grep -rn "^export " --include="*.ts" -A1 | grep -v "^--$" | grep -v "/\*\*"
+```
+
+### Classes Without Documentation
+
+```bash
+# Find classes without JSDoc
+grep -rn "^export class\|^class " --include="*.ts" | \
+  while read line; do
+    file=$(echo "$line" | cut -d: -f1)
+    linenum=$(echo "$line" | cut -d: -f2)
+    prev=$((linenum - 1))
+    if ! sed -n "${prev}p" "$file" | grep -q "\*/"; then
+      echo "$line"
+    fi
+  done
+```
+
+### Public Methods Without Documentation
+
+```bash
+# Find public methods (not private/protected) without JSDoc
+grep -rn "^\s*public\|^\s*async\s\+[a-z]" --include="*.ts" | \
+  grep -v "private\|protected\|constructor"
+```
+
+---
+
+## Finding Outdated Documentation
+
+### TODO/FIXME Comments
+
+```bash
+# Find all TODO/FIXME comments
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx"
+
+# Find TODOs older than 6 months (requires git)
+git log --since="6 months ago" --all --pretty=format: --name-only --diff-filter=D | \
+  xargs -I {} grep -l "TODO\|FIXME" {} 2>/dev/null
+```
+
+### Deprecated References
+
+```bash
+# Find @deprecated, @see, @link annotations that may be stale
+grep -rn "@see\|@link\|@deprecated" --include="*.ts"
+
+# Find references to potentially removed functions
+grep -rn "@see.*#[a-zA-Z]" --include="*.ts"
+```
+
+### Comment-Code Drift Indicators
+
+```bash
+# Find comments with numbers that might drift
+grep -rn "// .*[0-9]\+.*times\|// .*[0-9]\+.*retries\|// .*[0-9]\+.*max" --include="*.ts"
+
+# Find hardcoded numbers near comments
+grep -rn "for.*[0-9]\+\|while.*[0-9]\+\|< [0-9]\+\|<= [0-9]\+" --include="*.ts" -B2
+```
+
+---
+
+## Finding Documentation Smells
+
+### Magic Numbers (Need Comments)
+
+```bash
+# Find magic numbers that likely need explanation
+grep -rn "[^a-zA-Z_][0-9]\{3,\}[^a-zA-Z_0-9]" --include="*.ts" | \
+  grep -v "const\|enum\|type\|interface\|import"
+
+# Find percentages, timeouts, limits
+grep -rn "[0-9]\+%\|[0-9]\+ms\|[0-9]\+s\|Timeout\|Limit" --include="*.ts"
+```
+
+### Comments Explaining "What"
+
+```bash
+# Find likely "what" comments (loop, check, get, set, etc.)
+grep -rn "// [Ll]oop\|// [Cc]heck\|// [Gg]et\|// [Ss]et\|// [Aa]dd\|// [Rr]emove" --include="*.ts"
+
+# Find single-word comments
+grep -rn "// [A-Z][a-z]\+$" --include="*.ts"
+```
+
+### Empty Catch Blocks (Need Explanation)
+
+```bash
+# Find empty or minimal catch blocks
+grep -rn "catch.*{" --include="*.ts" -A2 | grep -E "^\s*}\s*$|// ignore"
+```
+
+---
+
+## README/Changelog Checks
+
+### README Freshness
+
+```bash
+# Check if README mentions removed functions
+# First, find removed exports in recent commits
+git diff HEAD~50..HEAD --name-only -- "*.ts" | \
+  xargs -I {} git diff HEAD~50..HEAD -- {} | \
+  grep "^-export" | cut -d' ' -f3 | \
+  while read func; do
+    grep -l "$func" README.md 2>/dev/null && echo "README references removed: $func"
+  done
+```
+
+### Changelog Completeness
+
+```bash
+# Find recent breaking changes not in CHANGELOG
+git log --oneline --since="1 month ago" | grep -i "breaking\|remove\|deprecate"
+
+# Check CHANGELOG has recent version
+head -20 CHANGELOG.md
+```
+
+### Example Code Validation
+
+```bash
+# Extract code blocks from README and try to validate imports
+grep -A10 '```typescript\|```javascript' README.md | \
+  grep "import\|require" | \
+  while read line; do
+    # Check if imported module/function still exists
+    echo "Checking: $line"
+  done
+```
+
+---
+
+## Automated Checks
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# Add to .git/hooks/pre-commit
+
+# Check for undocumented exports
+undocumented=$(grep -rn "^export function\|^export class" --include="*.ts" | \
+  while read line; do
+    file=$(echo "$line" | cut -d: -f1)
+    linenum=$(echo "$line" | cut -d: -f2)
+    prev=$((linenum - 1))
+    if ! sed -n "${prev}p" "$file" | grep -q "\*/"; then
+      echo "$line"
+    fi
+  done)
+
+if [ -n "$undocumented" ]; then
+  echo "ERROR: Undocumented exports found:"
+  echo "$undocumented"
+  exit 1
+fi
+```
+
+### CI Check
+
+```yaml
+# Add to CI pipeline
+documentation-check:
+  script:
+    - npm run docs:check  # Runs typedoc or similar
+    - |
+      # Check for stale TODOs
+      old_todos=$(grep -rn "TODO" --include="*.ts" | wc -l)
+      if [ "$old_todos" -gt 50 ]; then
+        echo "WARNING: $old_todos TODO comments found"
+      fi
+```