mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/visual-regression-testing/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: visual-regression-testing
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: visual regression, screenshot test, pixel diff, visual baseline, chromatic, percy, visual snapshot, component screenshot, visual comparison, layout shift detection, visual approval, screenshot diff
+compose: testing-standards
+---
+
+# Visual Regression Testing
+
+## When this skill activates
+
+This skill activates when implementing screenshot-based testing, configuring visual diff tools, managing visual baselines, or investigating unexpected UI changes. It applies to component-level visual testing (Storybook), page-level screenshots, and responsive layout verification.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Determine the scope: component-level (individual components in isolation) or page-level (full page renders).
+2. Select the tooling approach (Playwright screenshots, Chromatic, Percy, BackstopJS).
+3. Identify dynamic content that must be stabilized (timestamps, avatars, animations, ads).
+4. Define viewport sizes to capture (mobile: 375px, tablet: 768px, desktop: 1440px minimum).
+5. Establish the pixel diff threshold (recommended: 0.1% for strict, 0.5% for lenient).
+6. Confirm baseline images exist or plan initial baseline capture.
+
+### During
+
+**Core Workflow:**
+1. Capture baseline screenshots (the "known good" state).
+2. Make code changes (feature, refactor, dependency update).
+3. Capture new screenshots under identical conditions.
+4. Run pixel diff comparison between baseline and new.
+5. Review diffs: approve intentional changes, reject regressions.
+6. Update baselines for approved changes.
+
+**Handling Dynamic Content (Critical):**
+- **Timestamps/dates**: Mock to a fixed date (`2024-01-15T10:00:00Z`).
+- **Avatars/images**: Use deterministic placeholder images.
+- **Animations**: Disable CSS animations and transitions during capture.
+- **Cursor blink**: Hide input cursors via CSS override.
+- **Loading states**: Wait for network idle and all images loaded before capture.
+- **Random content**: Seed random generators or use fixed test data.
+- **Third-party widgets**: Hide or mock (chat widgets, analytics banners).
+
+**Component-Level Testing (Storybook + Chromatic):**
+- Every component gets a story with representative states (default, loading, error, empty, overflow).
+- Chromatic captures each story as a visual baseline automatically.
+- Review changes in Chromatic UI with side-by-side comparison.
+- Use `args` and `decorators` to control component state deterministically.
+- Group related stories to reduce noise in review.
+
+**Page-Level Testing (Playwright/BackstopJS):**
+- Navigate to page, wait for full render (network idle + specific element visible).
+- Capture at multiple viewports for responsive verification.
+- Use `page.screenshot({ fullPage: true })` for scroll content.
+- Clip to specific regions when full-page comparison is too noisy.
+- Set `maxDiffPixelRatio` threshold in Playwright config.
+
+**Diff Thresholds:**
+- **0.0%**: Exact match required. Use only for pixel-perfect components (logos, icons).
+- **0.1%**: Strict. Catches anti-aliasing differences across OS/browser combos.
+- **0.5%**: Standard. Tolerates minor rendering engine differences.
+- **1.0%**: Lenient. Use for pages with slight layout flexibility.
+- Above 1%: Likely a real regression — always investigate.
+
+**CI Integration:**
+- Run visual tests on every PR (component-level at minimum).
+- Full page-level suite on merge to main or nightly.
+- Store baseline images in version control or dedicated storage (LFS for large sets).
+- Block merge if unapproved visual diffs exist.
+- Provide direct links to diff viewer in PR comments.
+
+**Approval Workflow:**
+- Designer or frontend lead reviews visual diffs before approval.
+- Bulk approve when changes are intentional (theme update, design system change).
+- Document WHY a visual change was approved (link to design ticket).
+- Never auto-approve visual diffs — human review is the point.
+
+### After
+
+1. All visual diffs are reviewed and explicitly approved or rejected.
+2. Baselines are updated to reflect the new approved state.
+3. Dynamic content is fully stabilized (no flaky screenshots).
+4. Responsive breakpoints are covered (minimum 3 viewport widths).
+5. CI pipeline gates merge on unapproved visual changes.
+
+## Self-check before task completion
+
+- [ ] Dynamic content is fully mocked/frozen (no timestamps, no random data in screenshots).
+- [ ] Screenshots are captured after full render (network idle, fonts loaded, animations disabled).
+- [ ] Diff threshold is explicitly configured and appropriate for the content type.
+- [ ] Multiple viewport sizes are tested (mobile, tablet, desktop at minimum).
+- [ ] Approval workflow is defined (who reviews, how to approve, where to document).
+- [ ] Baseline images are stored durably and versioned with the code.
+- [ ] CI blocks deployment on unapproved visual regressions.
+- [ ] Flakiness is below 1% (re-run same code twice, expect identical screenshots).

package/.mindforge/skills/websocket-patterns/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: websocket-patterns
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: websocket pattern, websocket connection lifecycle, heartbeat mechanism, reconnection strategy, websocket rooms, channel subscription, websocket scaling, redis pub sub scaling, backpressure handling, websocket authentication, message ordering, binary protocol
+---
+
+# Skill — WebSocket Patterns
+
+## When this skill activates
+Any task involving WebSocket connection management, real-time communication,
+heartbeat/keepalive mechanisms, reconnection strategies, room/channel design,
+or WebSocket scaling across multiple server instances.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define the websocket connection lifecycle (upgrade, auth, message flow, close).
+2. Choose heartbeat interval and reconnection strategy.
+3. Determine scaling approach (Redis pub/sub, sticky sessions, etc.).
+
+### During implementation
+- Implement heartbeat mechanism (server ping every 30s).
+- Add exponential backoff with jitter for reconnection.
+- Handle backpressure (buffer limits, overflow policy).
+
+### After implementation
+- Load test concurrent connection capacity.
+- Verify reconnection behavior under network partitions.
+- Document WebSocket protocol in ARCHITECTURE.md.
+
+## Connection Lifecycle
+
+```
+HTTP Upgrade → Open → Authenticate → Subscribe → Message Loop → Ping/Pong → Close
+```
+
+### Upgrade
+- Client sends HTTP Upgrade request with `Sec-WebSocket-Key`.
+- Server responds with 101 Switching Protocols.
+- Connection is now bidirectional full-duplex.
+
+### Open
+- Connection established, ready for messages.
+- Server assigns connection ID for tracking.
+- Start heartbeat timer.
+
+### Authenticate
+- First message from client must be auth token.
+- Server validates token, associates connection with user.
+- Reject and close if auth fails (close code 4001).
+
+### Message Loop
+- Bidirectional message exchange.
+- Messages typed by application protocol (JSON envelope with `type` field).
+- Server processes commands, pushes events.
+
+### Close
+- Graceful: client/server sends close frame with reason code.
+- Ungraceful: TCP connection drops (detected by heartbeat timeout).
+- Clean up subscriptions, remove from rooms, release resources.
+
+## Heartbeat Mechanism
+
+### Server-Initiated Ping
+- Server sends WebSocket ping frame every 30 seconds.
+- Client automatically responds with pong (browser handles this).
+- If no pong received within 60 seconds: connection dead, close it.
+
+### Application-Level Heartbeat
+- Send JSON `{"type": "ping", "ts": 1234567890}` every 30s.
+- Client responds with `{"type": "pong", "ts": 1234567890}`.
+- Allows RTT measurement and connection quality monitoring.
+- Required when infrastructure (load balancers) strips WebSocket pings.
+
+### Idle Timeout
+- Close connections with no activity for 5 minutes.
+- Heartbeat keeps connection alive during quiet periods.
+- Differentiate: no data vs dead connection.
+
+## Reconnection Strategy
+
+### Exponential Backoff with Jitter
+```
+attempt 1: wait 1s + random(0-500ms)
+attempt 2: wait 2s + random(0-500ms)
+attempt 3: wait 4s + random(0-500ms)
+attempt 4: wait 8s + random(0-500ms)
+...
+max wait: 30s + random(0-500ms)
+```
+
+### Reconnection Behavior
+- On disconnect: immediately attempt reconnect (might be transient).
+- On failure: apply exponential backoff.
+- On reconnect success: re-authenticate, re-subscribe to channels.
+- Resume from last received message sequence number (gap detection).
+
+### Client State During Reconnection
+- Show "reconnecting..." indicator to user.
+- Buffer outgoing messages (send after reconnect).
+- Merge missed messages on reconnection (request gap fill from server).
+
+## Rooms and Channels
+
+### Topic-Based Subscriptions
+```json
+{"type": "subscribe", "channel": "chat:room-123"}
+{"type": "unsubscribe", "channel": "chat:room-123"}
+```
+
+### Room Semantics
+- Join: add connection to room's subscriber list.
+- Leave: remove connection from room's subscriber list.
+- Broadcast: send message to all connections in room.
+- Presence: track who is currently in room (online/offline).
+
+### Channel Naming Convention
+```
+{domain}:{resource_type}:{resource_id}
+chat:room:abc123
+orders:user:user456
+notifications:global
+```
+
+## Scaling Across Instances
+
+### Problem
+- WebSocket connections are stateful (pinned to one server).
+- Broadcasting must reach connections on ALL servers.
+- Server A has user X, Server B has user Y — both in same room.
+
+### Solution: Redis Pub/Sub
+```
+Server A publishes → Redis channel → Server B receives → delivers to local connections
+```
+
+- Each server subscribes to Redis channels matching its connections' rooms.
+- On broadcast: publish to Redis, all servers deliver to their local connections.
+- Redis Pub/Sub is fire-and-forget (acceptable for real-time messages).
+
+### Alternative: Sticky Sessions
+- Route same user to same server (via cookie or IP hash).
+- Simpler but limits horizontal scaling.
+- Fails on server restart (all connections drop).
+
+## Authentication
+
+### Token in Query Parameter (During Upgrade)
+```
+ws://example.com/ws?token=jwt_token_here
+```
+- Simple, works with browser WebSocket API.
+- Risk: token in URL may appear in logs.
+
+### Token in First Message (After Connect)
+```json
+{"type": "auth", "token": "jwt_token_here"}
+```
+- More secure (not in URL/logs).
+- Requires handling unauthenticated state.
+- Close connection if no auth within 5 seconds.
+
+### Token Refresh
+- Server sends `{"type": "token_expiring", "expires_in": 60}`.
+- Client sends new token before expiration.
+- If token expires: close connection, client reconnects with fresh token.
+
+## Backpressure Handling
+
+### Problem
+- Server produces messages faster than client can consume.
+- Client's buffer grows unbounded, eventually crashes.
+
+### Solutions
+
+#### Buffer with Limit
+- Set maximum buffer size per connection (e.g., 1000 messages).
+- When buffer full: drop oldest messages.
+- Notify client: `{"type": "lag_warning", "dropped": 47}`.
+
+#### Flow Control
+- Client sends acknowledgment every N messages.
+- Server pauses sending if no ack received.
+- Similar to TCP flow control at application level.
+
+#### Priority Queues
+- Critical messages (errors, auth) never dropped.
+- Real-time data (cursor positions) can be dropped.
+- Batch/compress low-priority messages during lag.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Is heartbeat mechanism implemented (30s ping, 60s timeout)?
+- [ ] Is reconnection using exponential backoff with jitter?
+- [ ] Is authentication handled (first message or query param)?
+- [ ] Is backpressure handled (buffer limit, drop policy)?
+- [ ] Is cross-instance scaling addressed (Redis pub/sub or equivalent)?
+- [ ] Are rooms/channels properly implemented with join/leave semantics?

package/.mindforge/skills/writing-plans/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: writing-plans
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: writing plan, plan writing, task decomposition, implementation plan, step by step plan, plan template, planning guide, plan structure, bite-sized tasks, plan format, plan methodology, plan checklist
+---
+
+# Skill — Writing Plans
+
+## When this skill activates
+Any task that requires producing an implementation plan, task decomposition,
+step-by-step instructions, or structured execution guide. This includes feature
+plans, migration plans, refactoring plans, and any multi-step work breakdown.
+
+## Mandatory actions when this skill is active
+
+### Before writing any plan
+1. **Gather complete context.** Read:
+   - The specification or requirement being planned for.
+   - The current codebase structure (file paths, existing patterns).
+   - Any constraints (tech stack, timeline, dependencies on other work).
+2. **Identify the scope boundary.** What is IN the plan vs OUT of scope?
+3. **Identify dependencies.** Which steps depend on other steps? Which can be parallel?
+
+### During plan writing
+
+#### Core Principle: NO PLACEHOLDERS
+Every step in the plan must contain **complete, executable instructions**. A plan
+fails its purpose if the executor has to figure out what goes in a placeholder.
+
+**Bad (placeholder):**
+```
+3. Add the authentication middleware to the routes.
+```
+
+**Good (complete):**
+```
+3. Add authentication middleware to API routes.
+   File: src/middleware/auth.ts
+   Create a new middleware function:
+   - Import `verifyJWT` from `src/lib/jwt.ts`
+   - Extract the `Authorization` header, strip "Bearer " prefix
+   - Call `verifyJWT(token)` — if it throws, return 401 with `{ error: "Invalid token" }`
+   - If valid, attach `req.user = decoded` and call `next()`
+
+   File: src/routes/api.ts
+   - Import `authMiddleware` from `src/middleware/auth.ts`
+   - Add `router.use("/api/v1/protected", authMiddleware)` before the route definitions
+     on line ~45 (after the public routes, before the protected group)
+
+   Verify: Run `curl -H "Authorization: Bearer invalid" localhost:3000/api/v1/protected/me`
+   Expected: 401 response with `{"error": "Invalid token"}`
+```
+
+#### Plan Structure Template
+
+```markdown
+# Plan: [Feature/Task Name]
+
+## Context
+[1-3 sentences: WHY this work exists. Link to spec/ticket if applicable.]
+
+## Scope
+- IN: [What this plan covers]
+- OUT: [What is explicitly excluded]
+
+## Prerequisites
+- [ ] [Anything that must be true before starting step 1]
+
+## Steps
+
+### Step 1: [Verb + Object] (estimated: Xmin)
+**What**: [One sentence summary]
+**Files**:
+- `path/to/file.ts` — [what changes]
+- `path/to/other.ts` — [what changes]
+
+**Details**:
+[Complete instructions with exact code patterns, not pseudocode]
+
+**Verify**: [Exact command or check to confirm this step worked]
+Expected: [What success looks like]
+
+---
+
+### Step 2: [Verb + Object] (estimated: Xmin)
+**Depends on**: Step 1
+...
+
+## Verification (End-to-End)
+[How to verify the entire plan was executed correctly]
+
+## Rollback
+[How to undo this work if something goes wrong]
+```
+
+#### Step Design Rules
+1. **Bite-sized**: Each step is independently verifiable. If you cannot verify a step
+   without completing the next step, merge them or restructure.
+2. **Atomic**: Each step makes one logical change. "Add the model AND the migration
+   AND the API route AND the tests" is four steps, not one.
+3. **Ordered by dependency**: Steps that depend on previous steps come after them.
+   Independent steps are noted as parallelizable.
+4. **Specific file paths**: Every step names exact files. Never say "the config file"
+   when you mean `src/config/database.ts`.
+5. **Include the WHY**: If a step has a non-obvious reason, explain it inline. The
+   executor should never wonder "why are we doing this?"
+6. **Verification after every step**: Each step ends with a concrete check. Prefer
+   runnable commands (`npm test`, `curl`, `grep`) over subjective checks ("looks right").
+
+#### Handling Complexity
+- **If a step has > 10 lines of instructions**: Split it into sub-steps (1a, 1b, 1c).
+- **If a plan has > 15 steps**: Group into phases with phase-level verification gates.
+- **If there are conditional paths** ("if X then do Y, else do Z"): Write both paths
+  explicitly. Note the decision criteria clearly.
+- **If a step requires research** ("find the best library for X"): That is a separate
+  pre-plan task. Plans should not contain open-ended research.
+
+#### Estimations
+- Include time estimates per step (in minutes).
+- Be realistic: include time for verification and debugging.
+- Total plan time = sum of steps + 20% buffer for unexpected issues.
+- If total exceeds 4 hours: break into multiple plans with clear handoff points.
+
+#### Dependencies and Parallelism
+- Mark each step with `Depends on: Step N` or `Depends on: None (parallelizable)`.
+- Group parallelizable steps explicitly:
+  ```
+  ### Steps 3-5 (parallelizable — no dependencies between them)
+  ```
+- Never leave implicit dependencies. If step 4 silently requires step 3's output,
+  make it explicit.
+
+### After writing the plan
+1. **Self-review with the "zero context" test**: Could someone unfamiliar with this
+   codebase follow these steps and produce a working result? If any step requires
+   knowledge not in the plan, add it.
+2. **Check for placeholder language**: Search for words like "appropriate", "relevant",
+   "as needed", "etc.", "similar to". Replace each with specifics.
+3. **Verify file paths exist**: Every path referenced in the plan should be a real file
+   (or explicitly marked as "create new file").
+4. **Confirm verification steps are runnable**: Each verify command should work
+   copy-pasted into a terminal.
+
+## Plan quality anti-patterns to flag
+
+- "Update the configuration as appropriate" (what configuration? what value?)
+- "Add error handling" (what errors? what handling? what response?)
+- "Refactor the module" (which module? what pattern? what is the target state?)
+- "Write tests" (what tests? what cases? what assertions?)
+- Steps without verification (how do you know it worked?)
+- Steps that combine 3+ unrelated changes (should be split)
+- Vague time estimates ("a while", "some time") instead of minutes
+- Missing rollback plan (what if step 7 fails and you need to undo steps 1-6?)
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Every step has specific file paths (no "the relevant file").
+- [ ] Every step has a verification check with expected output.
+- [ ] No placeholder language ("as needed", "appropriate", "etc.").
+- [ ] Dependencies between steps are explicit.
+- [ ] Time estimates are included per step.
+- [ ] A zero-context reader could follow the plan without asking questions.
+- [ ] Rollback instructions are included.
+- [ ] Plan scope (IN/OUT) is clearly defined.
+- [ ] If > 15 steps, organized into phases with phase-level gates.
+- [ ] All file paths verified to exist (or marked as "new file").

package/.mindforge/skills/writing-skills/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: writing-skills
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: writing skill, skill authoring, skill format, skill schema, skill template, how to write skill, skill frontmatter, skill structure, skill design, skill best practice, reusable skill, skill guide
+---
+
+# Skill — Writing Skills
+
+## When this skill activates
+Any task involving authoring, designing, or reviewing MindForge skill files.
+This includes creating new skills from scratch, refactoring existing skills,
+reviewing skill quality, or understanding the skill schema and conventions.
+
+## Mandatory actions when this skill is active
+
+### Before writing any skill
+1. **Clarify the skill's purpose.** Answer these three questions:
+   - What problem does this skill solve? (One sentence.)
+   - When should it activate? (Specific scenarios, not vague categories.)
+   - What does it make the agent DO differently? (Observable behavior change.)
+2. **Check for conflicts.** Review existing skills in `.mindforge/skills/` to ensure:
+   - No trigger overlap (same keyword activating two different skills).
+   - No scope overlap (two skills giving contradictory instructions for the same task).
+   - Compose relationship is correct (child skill composes parent, not duplicates it).
+3. **Determine if this is a standalone skill or a composed skill.**
+   - Standalone: activates independently, covers a complete domain.
+   - Composed (`compose: parent-skill`): extends a parent skill with specialization.
+     The parent's instructions apply AND the child's instructions add specificity.
+
+### During skill authoring
+
+#### Frontmatter Schema (YAML)
+```yaml
+---
+name: skill-name-kebab-case       # Required. Unique identifier.
+version: 1.0.0                     # Required. SemVer.
+min_mindforge_version: 10.0.6      # Required. Minimum framework version.
+status: stable                     # Required. One of: draft, beta, stable, deprecated.
+triggers: keyword1, keyword2, compound phrase, another trigger
+                                   # Required. Comma-separated. 12+ recommended.
+compose: parent-skill-name         # Optional. Name of parent skill this extends.
+---
+```
+
+**Field rules:**
+- `name`: Must match the directory name. Kebab-case. Globally unique across the registry.
+- `version`: Follows semantic versioning. Bump minor for new content, major for breaking trigger changes.
+- `min_mindforge_version`: The oldest framework version that supports this skill's features.
+- `status`:
+  - `draft` — Work in progress, may have incomplete sections.
+  - `beta` — Functional but not battle-tested. May change.
+  - `stable` — Production-ready. Trigger changes require major version bump.
+  - `deprecated` — Superseded by another skill. Include migration note in body.
+- `triggers`: The activation keywords. See "Trigger Design" section below.
+- `compose`: If set, this skill inherits all instructions from the named parent skill.
+  The agent applies BOTH the parent and this skill when activated.
+
+#### Body Structure
+```markdown
+# Skill — [Human-Readable Name]
+
+## When this skill activates
+[1-3 sentences describing the exact scenarios. Be specific enough that an agent
+can determine yes/no whether this skill applies.]
+
+## Mandatory actions when this skill is active
+
+### Before [writing code / starting the task]
+[Numbered list of preparation steps. What must be checked/read/decided first.]
+
+### During [implementation / the task]
+[The core instructions. Checklists, patterns, code examples, decision trees.
+This is the largest section. Organize with sub-headings.]
+
+### After [implementation / the task]
+[Verification steps. What to check, run, or validate before marking done.]
+
+## [Optional: Domain-specific sections]
+[Tables, reference data, anti-patterns, decision matrices, etc.]
+
+## Self-check before task completion
+[Checkbox list. Every skill MUST end with this section. These are the minimum
+criteria that must be true before the agent considers the task complete.]
+```
+
+#### Trigger Design (Critical for Activation Accuracy)
+
+**Quantity**: Aim for 12-20 triggers per skill. Fewer = missed activations. More = false positives.
+
+**Types of triggers to include:**
+1. **Direct name** — The skill's core concept: `kubernetes deployment`, `react performance`.
+2. **Tool/library names** — Specific tools the skill covers: `cProfile`, `React.memo`, `helm chart`.
+3. **Problem descriptions** — How users describe the need: `python bottleneck`, `unnecessary re-render`.
+4. **Action phrases** — What users ask to do: `write a plan`, `create a skill`.
+5. **Compound phrases** — Multi-word to avoid conflicts: `discriminated union` not just `union`.
+
+**Trigger design rules:**
+- Use compound phrases (2-3 words) to avoid false positives. `type` alone would fire on
+  every TypeScript task. `conditional type` is specific.
+- Include both the noun and verb forms: `profiling` AND `profile python`.
+- Test mentally: "If a user says this trigger phrase in a prompt, should THIS skill activate?"
+  If the answer is "maybe" — the trigger is too vague.
+- Never use single common words as triggers (`code`, `fix`, `build`, `test`).
+- Avoid triggers that overlap with other skills. Run a mental diff against similar skills.
+
+**Trigger conflict resolution:**
+- If two skills share a trigger, the more specific skill wins.
+- If you cannot determine specificity, add a qualifying word to disambiguate.
+- Example conflict: both `performance` and `react-performance` trigger on "performance".
+  Resolution: `react-performance` uses `react performance` (compound), the generic
+  `performance` skill handles the unqualified keyword.
+
+#### Content Principles
+
+1. **Actionable, not advisory.** Say "Do X" not "Consider doing X" or "It's good practice to X".
+   - Bad: "You should consider adding error handling."
+   - Good: "Add try/catch around the database call. Log the error with context. Return 500."
+
+2. **Checklists, not essays.** Agents process structured lists faster than paragraphs.
+   - Bad: "When working with generics, it's important to think about constraints because
+     without them the type parameter is too broad and you lose type safety."
+   - Good: "- Always constrain generic parameters: `<T extends Base>` not bare `<T>`."
+
+3. **Complete code examples over descriptions.** Show the pattern, not just name it.
+   - Bad: "Use the builder pattern for complex objects."
+   - Good: [10-line code example of the builder pattern in the project's language]
+
+4. **Under 500 lines.** If a skill exceeds 500 lines, it is trying to cover too much.
+   Split into a parent skill + composed children.
+   - Example: `performance` (parent, 120 lines of general principles) +
+     `python-performance` (child, composes performance, 400 lines of Python specifics).
+
+5. **Decision trees for conditional logic.** When the right action depends on context,
+   provide explicit if/then:
+   ```
+   - IF the list has > 50 items → use virtualization
+   - IF the list has 10-50 items → use React.memo on list items
+   - IF the list has < 10 items → no optimization needed
+   ```
+
+6. **Anti-patterns section.** Include a list of common mistakes to flag. Agents benefit
+   from knowing what NOT to do as much as what to do.
+
+#### Quality Standards for Skill Content
+
+- Every code example must be syntactically valid (could be pasted and would compile).
+- All file paths in examples must use the project's actual structure conventions.
+- Version numbers in examples must not be outdated (review annually).
+- Commands must include expected output or success criteria.
+- If a skill references an external tool, include the install command.
+
+### After writing the skill
+
+1. **Validate frontmatter.** Confirm all required fields present, triggers are comma-separated,
+   version is valid SemVer.
+2. **Trigger evaluation test.** For each trigger, mentally construct a user prompt that
+   contains it and verify the skill SHOULD activate:
+   ```
+   Trigger: "discriminated union"
+   Test prompt: "I need to model payment states as a discriminated union"
+   Should activate? YES — this is exactly about TypeScript advanced types.
+   ```
+3. **Conflict scan.** Compare triggers against all existing skills:
+   ```bash
+   grep -r "^triggers:" .mindforge/skills/*/SKILL.md
+   ```
+   Flag any overlap and resolve per the rules above.
+4. **Register in MANIFEST.md** (if the project maintains one). Add the skill entry
+   with name, version, status, and trigger count.
+5. **Test via eval harness** (if available):
+   ```bash
+   mindforge eval-skill --skill=new-skill-name --prompts=20
+   ```
+   Verify activation precision > 90% and recall > 85%.
+
+## Skill review checklist (for reviewing others' skills)
+
+| Criterion | Pass/Fail |
+|---|---|
+| Frontmatter has all required fields | |
+| 12+ triggers, all compound (2+ words) | |
+| No single-word triggers | |
+| No trigger conflicts with existing skills | |
+| "When this skill activates" is specific (yes/no determinable) | |
+| Mandatory actions cover Before/During/After | |
+| Self-check section present with checkboxes | |
+| Content is actionable (imperatives, not suggestions) | |
+| Code examples are syntactically valid | |
+| Under 500 lines total | |
+| No placeholder language ("as appropriate", "etc.") | |
+
+## Skill lifecycle
+
+| Status | Meaning | Allowed changes |
+|---|---|---|
+| draft | Under construction | Anything |
+| beta | Functional, being tested | Content changes, trigger additions |
+| stable | Production | Content patches only. Trigger changes = major version bump |
+| deprecated | Being replaced | Only add migration notes pointing to successor |
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Frontmatter validates (all required fields, valid SemVer, 12+ triggers).
+- [ ] No trigger conflicts with existing skills (grep verified).
+- [ ] Body follows the standard structure (activation, Before/During/After, self-check).
+- [ ] Content is actionable (imperatives, checklists, code examples).
+- [ ] Under 500 lines total.
+- [ ] At least one code example included for the primary pattern.
+- [ ] Self-check section has 5+ checkboxes covering the skill's key requirements.
+- [ ] Trigger evaluation: 5+ test prompts mentally validated.
+- [ ] Registered in MANIFEST.md (if applicable).
+- [ ] No placeholder language in the body.