devflow-kit 1.8.3 → 2.0.1

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

@@ -1,190 +0,0 @@
-# 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
-```

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

@@ -1,189 +0,0 @@
-# Correct Documentation Patterns
-
-Extended examples of proper documentation. See parent `SKILL.md` for brief examples and severity guidelines.
-
----
-
-## Code Documentation Patterns
-
-### Proper JSDoc for Complex Functions
-
-```typescript
-/**
- * Calculates prorated billing amount when switching plans mid-cycle.
- *
- * @param plan - The new plan to prorate to
- * @param startDate - When the new plan starts
- * @param endDate - End of current billing cycle
- * @param previousPlan - Optional previous plan for credit calculation
- * @returns Prorated amount in cents (can be negative for downgrades)
- *
- * @example
- * // Upgrading mid-month
- * calculateProratedAmount(premiumPlan, new Date('2024-01-15'), new Date('2024-01-31'))
- * // Returns: 1645 (cents)
- *
- * @throws {InvalidDateRangeError} If startDate is after endDate
- */
-export function calculateProratedAmount(
-  plan: Plan,
-  startDate: Date,
-  endDate: Date,
-  previousPlan?: Plan
-): number {
-  // ...
-}
-```
-
-**Key elements**: Purpose, all params, return type with units, example usage, error conditions.
-
-### Comments That Explain "Why"
-
-```typescript
-// Filter to active users only - inactive users should not receive
-// promotional emails per GDPR consent requirements
-const activeUsers = users.filter(u => u.active);
-```
-
-**Key elements**: Business reason (GDPR), not mechanical description.
-
-### Algorithm Documentation
-
-```typescript
-/**
- * Schedules tasks using weighted shortest job first (WSJF) algorithm.
- *
- * Priority score = (priority * urgency) / duration
- * Higher scores are scheduled first.
- *
- * Tasks are placed starting 1.5x their duration before deadline
- * to allow buffer for overruns.
- *
- * @see https://www.scaledagileframework.com/wsjf/
- */
-function schedule(tasks: Task[]): Schedule {
-  // ...
-}
-```
-
-**Key elements**: Algorithm name, formula explanation, rationale for magic numbers, external reference.
-
----
-
-## API Documentation Patterns
-
-### Complete Parameter Documentation
-
-```typescript
-/**
- * Creates a new subscription for a user.
- *
- * @param userId - The unique identifier of the user
- * @param planId - The plan to subscribe to (from /plans endpoint)
- * @param options - Optional configuration
- * @param options.trialDays - Number of trial days (default: 0, max: 30)
- * @param options.couponCode - Discount coupon to apply
- * @param options.startDate - When to start (default: now)
- *
- * @returns The created subscription with payment details
- *
- * @throws {UserNotFoundError} If userId doesn't exist
- * @throws {PlanNotFoundError} If planId doesn't exist
- * @throws {InvalidCouponError} If coupon is expired or invalid
- */
-async function createSubscription(
-  userId: string,
-  planId: string,
-  options?: SubscriptionOptions
-): Promise<Subscription>;
-```
-
-**Key elements**: All params including nested options, defaults, constraints, all error types.
-
-### Return Value Documentation
-
-```typescript
-/**
- * Fetches aggregated analytics data for the date range.
- *
- * @param range - Start and end dates for the query
- * @returns Analytics data including:
- *   - totalVisitors: Unique visitor count
- *   - pageViews: Total page view count
- *   - bounceRate: Percentage (0-100) of single-page sessions
- *   - avgSessionDuration: Average session length in seconds
- *   - topPages: Array of {path, views} sorted by views desc
- */
-async function getAnalytics(range: DateRange): Promise<Analytics>;
-```
-
-**Key elements**: Shape of return object, units (percentage, seconds), sorting order.
-
-### Error Documentation
-
-```typescript
-/**
- * Transfers funds between accounts.
- *
- * @throws {InsufficientFundsError} If source account balance < amount
- * @throws {AccountNotFoundError} If either account doesn't exist
- * @throws {AccountFrozenError} If either account is frozen
- * @throws {TransferLimitError} If amount exceeds daily transfer limit
- * @throws {SameAccountError} If from === to
- */
-async function transferFunds(from: string, to: string, amount: number): Promise<void>;
-```
-
-**Key elements**: All possible error types with conditions that trigger them.
-
----
-
-## Alignment Patterns
-
-### Constants Instead of Magic Numbers
-
-```typescript
-const MAX_RETRIES = 5;
-
-// Retries up to MAX_RETRIES times with exponential backoff
-async function fetchWithRetry(url: string) {
-  for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
-}
-```
-
-**Key elements**: Named constant keeps comment and code in sync automatically.
-
-### Up-to-Date README
-
-```markdown
-## Installation
-npm install mypackage@^2.0.0
-
-## Usage
-import { newFunction } from 'mypackage';
-await newFunction({ /* new options */ });
-
-## Migration from v1
-See [MIGRATION.md](./MIGRATION.md) for upgrade instructions.
-```
-
-**Key elements**: Correct version, working examples, migration guidance.
-
-### Proper Changelog
-
-```markdown
-## [2.0.0] - 2024-01-15
-
-### Breaking Changes
-- `createUser()` now returns `Promise<Result<User>>` instead of `Promise<User>`
-- Removed deprecated `oldFunction()` - use `newFunction()` instead
-- Minimum Node.js version is now 18
-
-### Added
-- New `validateUser()` function for input validation
-
-### Changed
-- Improved error messages for authentication failures
-```
-
-**Key elements**: Breaking changes highlighted first, migration hints, categorized changes.

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

@@ -1,163 +0,0 @@
-# Documentation Violation Examples
-
-Extended examples of documentation anti-patterns. See parent `SKILL.md` for brief examples and severity guidelines.
-
----
-
-## Code Documentation Violations
-
-### Missing Docstrings/JSDoc
-
-```typescript
-// VIOLATION: Complex function without documentation
-export function calculateProratedAmount(
-  plan: Plan,
-  startDate: Date,
-  endDate: Date,
-  previousPlan?: Plan
-): number {
-  // 50 lines of complex billing logic...
-}
-```
-
-**Why it's a problem**: Complex billing logic with edge cases (negative amounts for downgrades, credit calculations) is impossible to use correctly without documentation.
-
-### Outdated Comments
-
-```typescript
-// VIOLATION: Comment doesn't match code
-// Returns user's full name
-function getDisplayName(user: User): string {
-  return user.username;  // Actually returns username, not full name!
-}
-
-// VIOLATION: TODO that's been done
-// TODO: Add validation
-function processInput(input: string) {
-  if (!isValid(input)) throw new Error('Invalid');  // Validation exists!
-  // ...
-}
-```
-
-**Why it's a problem**: Misleading comments cause bugs when developers trust them over reading the code.
-
-### Comments Explaining "What" Instead of "Why"
-
-```typescript
-// VIOLATION: Describes what code does (obvious from code)
-// Loop through users
-for (const user of users) {
-  // Check if user is active
-  if (user.active) {
-    // Add user to list
-    activeUsers.push(user);
-  }
-}
-```
-
-**Why it's a problem**: These comments add noise without value. The code already says what it does.
-
-### Complex Code Without Explanation
-
-```typescript
-// VIOLATION: Magic algorithm without explanation
-function schedule(tasks: Task[]): Schedule {
-  return tasks
-    .sort((a, b) => (b.priority * b.urgency) / b.duration - (a.priority * a.urgency) / a.duration)
-    .reduce((schedule, task) => {
-      const slot = findSlot(schedule, task, task.deadline - task.duration * 1.5);
-      return slot ? addToSchedule(schedule, task, slot) : schedule;
-    }, emptySchedule());
-}
-```
-
-**Why it's a problem**: The WSJF algorithm and 1.5x buffer are non-obvious. Future maintainers will be confused or afraid to modify.
-
----
-
-## API Documentation Violations
-
-### Missing Parameter Descriptions
-
-```typescript
-// VIOLATION: Parameters unexplained
-/**
- * Creates a new subscription.
- */
-async function createSubscription(
-  userId: string,
-  planId: string,
-  options?: SubscriptionOptions
-): Promise<Subscription>;
-```
-
-**Why it's a problem**: Callers don't know valid values for `planId`, what `options` are available, or constraints on parameters.
-
-### Missing Return Value Documentation
-
-```typescript
-// VIOLATION: Return shape unknown
-/**
- * Fetches analytics data.
- */
-async function getAnalytics(range: DateRange): Promise<Analytics>;
-```
-
-**Why it's a problem**: Consumers must read implementation to understand the shape of `Analytics`.
-
-### Missing Error Documentation
-
-```typescript
-// VIOLATION: Errors not documented
-async function transferFunds(from: string, to: string, amount: number): Promise<void>;
-```
-
-**Why it's a problem**: Callers don't know what errors to catch or handle. They'll either catch everything or miss important cases.
-
----
-
-## Alignment Violations
-
-### Code-Comment Drift
-
-```typescript
-// BEFORE: Comment matches
-// Retries up to 3 times with exponential backoff
-async function fetchWithRetry(url: string) {
-  for (let i = 0; i < 3; i++) { /* ... */ }
-}
-
-// AFTER: Code changed, comment didn't
-// Retries up to 3 times with exponential backoff
-async function fetchWithRetry(url: string) {
-  for (let i = 0; i < 5; i++) { /* ... */ }  // Now 5 retries!
-}
-```
-
-**Why it's a problem**: Developers relying on the comment will expect different behavior than actual.
-
-### Stale README
-
-```markdown
-<!-- VIOLATION: README doesn't reflect reality -->
-
-## Installation
-npm install mypackage
-
-## Usage
-const { oldFunction } = require('mypackage');
-oldFunction(); // This function was removed!
-```
-
-**Why it's a problem**: New users follow outdated instructions and immediately hit errors.
-
-### Missing Changelog Entries
-
-```markdown
-<!-- VIOLATION: Breaking change not documented -->
-
-## [2.0.0] - 2024-01-15
-- Updated dependencies
-```
-
-**Why it's a problem**: Users upgrading have no warning about breaking changes and no migration path.