@kinqs/brainrouter-mcp-server 0.3.4

package/skills/lifecycle/migration-skill/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: migration-skill
+description: Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.
+hints:
+  - Check openSrc/ or existing project files for deprecated systems or migration patterns if available.
+  - Rely on backward-compatible adapter interfaces to let old consumers interact with new systems smoothly.
+  - Use the Strangler Pattern to route traffic incrementally from old code paths to new ones.
+  - Confirm active usage has dropped to absolute zero via logs/metrics before completely deleting code.
+  - Adhere to the Churn Rule: if you own the code being retired, provide easy-to-use migration tools or scripts.
+---
+
+# Deprecation and Migration
+
+## Overview
+
+Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.
+
+Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.
+
+## When to Use
+
+- Replacing an old system, API, or library with a new one
+- Sunsetting a feature that's no longer needed
+- Consolidating duplicate implementations
+- Removing dead code that nobody owns but everybody depends on
+- Planning the lifecycle of a new system (deprecation planning starts at design time)
+- Deciding whether to maintain a legacy system or invest in migration
+
+## Core Principles
+
+### Code Is a Liability
+
+Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
+
+### Hyrum's Law Makes Removal Hard
+
+With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.
+
+### Deprecation Planning Starts at Design Time
+
+When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.
+
+## The Deprecation Decision
+
+Before deprecating anything, answer these questions:
+
+```
+1. Does this system still provide unique value?
+   → If yes, maintain it. If no, proceed.
+
+2. How many users/consumers depend on it?
+   → Quantify the migration scope.
+
+3. Does a replacement exist?
+   → If no, build the replacement first. Don't deprecate without an alternative.
+
+4. What's the migration cost for each consumer?
+   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
+
+5. What's the ongoing maintenance cost of NOT deprecating?
+   → Security risk, engineer time, opportunity cost of complexity.
+```
+
+## Compulsory vs Advisory Deprecation
+
+| Type | When to Use | Mechanism |
+|------|-------------|-----------|
+| **Advisory** | Migration is optional, old system is stable | Warnings, documentation, nudges. Users migrate on their own timeline. |
+| **Compulsory** | Old system has security issues, blocks progress, or maintenance cost is unsustainable | Hard deadline. Old system will be removed by date X. Provide migration tooling. |
+
+**Default to advisory.** Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.
+
+## The Migration Process
+
+### Step 1: Build the Replacement
+
+Don't deprecate without a working alternative. The replacement must:
+
+- Cover all critical use cases of the old system
+- Have documentation and migration guides
+- Be proven in production (not just "theoretically better")
+
+### Step 2: Announce and Document
+
+```markdown
+## Deprecation Notice: OldService
+
+**Status:** Deprecated as of 2025-03-01
+**Replacement:** NewService (see migration guide below)
+**Removal date:** Advisory — no hard deadline yet
+**Reason:** OldService requires manual scaling and lacks observability.
+            NewService handles both automatically.
+
+### Migration Guide
+1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
+2. Update configuration (see examples below)
+3. Run the migration verification script: `npx migrate-check`
+```
+
+### Step 3: Migrate Incrementally
+
+Migrate consumers one at a time, not all at once. For each consumer:
+
+```
+1. Identify all touchpoints with the deprecated system
+2. Update to use the replacement
+3. Verify behavior matches (tests, integration checks)
+4. Remove references to the old system
+5. Confirm no regressions
+```
+
+**The Churn Rule:** If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.
+
+### Step 4: Remove the Old System
+
+Only after all consumers have migrated:
+
+```
+1. Verify zero active usage (metrics, logs, dependency analysis)
+2. Remove the code
+3. Remove associated tests, documentation, and configuration
+4. Remove the deprecation notices
+5. Celebrate — removing code is an achievement
+```
+
+## Migration Patterns
+
+### Strangler Pattern
+
+Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.
+
+```
+Phase 1: New system handles 0%, old handles 100%
+Phase 2: New system handles 10% (canary)
+Phase 3: New system handles 50%
+Phase 4: New system handles 100%, old system idle
+Phase 5: Remove old system
+```
+
+### Adapter Pattern
+
+Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.
+
+```typescript
+// Adapter: old interface, new implementation
+class LegacyTaskService implements OldTaskAPI {
+  constructor(private newService: NewTaskService) {}
+
+  // Old method signature, delegates to new implementation
+  getTask(id: number): OldTask {
+    const task = this.newService.findById(String(id));
+    return this.toOldFormat(task);
+  }
+}
+```
+
+### Feature Flag Migration
+
+Use feature flags to switch consumers from old to new system one at a time:
+
+```typescript
+function getTaskService(userId: string): TaskService {
+  if (featureFlags.isEnabled('new-task-service', { userId })) {
+    return new NewTaskService();
+  }
+  return new LegacyTaskService();
+}
+```
+
+## Zombie Code
+
+Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:
+
+- No commits in 6+ months but active consumers exist
+- No assigned maintainer or team
+- Failing tests that nobody fixes
+- Dependencies with known vulnerabilities that nobody updates
+- Documentation that references systems that no longer exist
+
+**Response:** Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It still works, why remove it?" | Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently. |
+| "Someone might need it later" | If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding. |
+| "The migration is too expensive" | Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term. |
+| "We'll deprecate it after we finish the new system" | Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now. |
+| "Users will migrate on their own" | They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule). |
+| "We can maintain both systems indefinitely" | Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost. |
+
+## Red Flags
+
+- Deprecated systems with no replacement available
+- Deprecation announcements with no migration tooling or documentation
+- "Soft" deprecation that's been advisory for years with no progress
+- Zombie code with no owner and active consumers
+- New features added to a deprecated system (invest in the replacement instead)
+- Deprecation without measuring current usage
+- Removing code without verifying zero active consumers
+
+## Required Checks
+
+After completing a deprecation:
+
+- [ ] Replacement is production-proven and covers all critical use cases.
+- [ ] Migration guide exists with concrete steps and examples.
+- [ ] All active consumers have been migrated (verified by metrics/logs).
+- [ ] Old code, tests, documentation, and configuration are fully removed.
+- [ ] No references to the deprecated system remain in the codebase.
+- [ ] Deprecation notices are removed (they served their purpose).
+
+## Verification
+After completing the skill, confirm:
+- [ ] Active traffic/call metrics are monitored to guarantee zero active dependency on the deprecated path.
+- [ ] Backward-compatible adapters or feature flag selectors are thoroughly unit tested before sunsetting old versions.
+- [ ] The deprecated code block, associated test suites, and dead documentation are fully purged from the codebase.

package/skills/lifecycle/shipping-skill/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: shipping-skill
+description: Prepares production launches. Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.
+hints:
+  - Check openSrc/ or existing project templates for launch/deployment procedures if available.
+  - Structure releases using feature flags to decouple code deployment from functional release.
+  - Implement a concrete, verified rollback script for codebase versions and database structures.
+  - Evaluate pre-launch checklists covering performance targets, accessibility, and security standards.
+  - Monitor application, client-side, and infrastructure logs closely for at least 15-30 minutes after deployment.
+---
+
+# Shipping and Launch
+
+## Overview
+
+Ship with confidence. The goal is not just to deploy — it's to deploy safely, with monitoring in place, a rollback plan ready, and a clear understanding of what success looks like. Every launch should be reversible, observable, and incremental.
+
+## When to Use
+
+- Deploying a feature to production for the first time
+- Releasing a significant change to users
+- Migrating data or infrastructure
+- Opening a beta or early access program
+- Any deployment that carries risk (all of them)
+
+## The Pre-Launch Checklist
+
+### Code Quality
+
+- [ ] All tests pass (unit, integration, e2e)
+- [ ] Build succeeds with no warnings
+- [ ] Lint and type checking pass
+- [ ] Code reviewed and approved
+- [ ] No TODO comments that should be resolved before launch
+- [ ] No `console.log` debugging statements in production code
+- [ ] Error handling covers expected failure modes
+
+### Security
+
+- [ ] No secrets in code or version control
+- [ ] `npm audit` shows no critical or high vulnerabilities
+- [ ] Input validation on all user-facing endpoints
+- [ ] Authentication and authorization checks in place
+- [ ] Security headers configured (CSP, HSTS, etc.)
+- [ ] Rate limiting on authentication endpoints
+- [ ] CORS configured to specific origins (not wildcard)
+
+### Performance
+
+- [ ] Core Web Vitals within "Good" thresholds
+- [ ] No N+1 queries in critical paths
+- [ ] Images optimized (compression, responsive sizes, lazy loading)
+- [ ] Bundle size within budget
+- [ ] Database queries have appropriate indexes
+- [ ] Caching configured for static assets and repeated queries
+
+### Accessibility
+
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader can convey page content and structure
+- [ ] Color contrast meets WCAG 2.1 AA (4.5:1 for text)
+- [ ] Focus management correct for modals and dynamic content
+- [ ] Error messages are descriptive and associated with form fields
+- [ ] No accessibility warnings in axe-core or Lighthouse
+
+### Infrastructure
+
+- [ ] Environment variables set in production
+- [ ] Database migrations applied (or ready to apply)
+- [ ] DNS and SSL configured
+- [ ] CDN configured for static assets
+- [ ] Logging and error reporting configured
+- [ ] Health check endpoint exists and responds
+
+### Documentation
+
+- [ ] README updated with any new setup requirements
+- [ ] API documentation current
+- [ ] ADRs written for any architectural decisions
+- [ ] Changelog updated
+- [ ] User-facing documentation updated (if applicable)
+
+## Feature Flag Strategy
+
+Ship behind feature flags to decouple deployment from release:
+
+```typescript
+// Feature flag check
+const flags = await getFeatureFlags(userId);
+
+if (flags.taskSharing) {
+  // New feature: task sharing
+  return <TaskSharingPanel task={task} />;
+}
+
+// Default: existing behavior
+return null;
+```
+
+**Feature flag lifecycle:**
+
+```
+1. DEPLOY with flag OFF     → Code is in production but inactive
+2. ENABLE for team/beta     → Internal testing in production environment
+3. GRADUAL ROLLOUT          → 5% → 25% → 50% → 100% of users
+4. MONITOR at each stage    → Watch error rates, performance, user feedback
+5. CLEAN UP                 → Remove flag and dead code path after full rollout
+```
+
+**Rules:**
+- Every feature flag has an owner and an expiration date
+- Clean up flags within 2 weeks of full rollout
+- Don't nest feature flags (creates exponential combinations)
+- Test both flag states (on and off) in CI
+
+## Staged Rollout
+
+### The Rollout Sequence
+
+```
+1. DEPLOY to staging
+   └── Full test suite in staging environment
+   └── Manual smoke test of critical flows
+
+2. DEPLOY to production (feature flag OFF)
+   └── Verify deployment succeeded (health check)
+   └── Check error monitoring (no new errors)
+
+3. ENABLE for team (flag ON for internal users)
+   └── Team uses the feature in production
+   └── 24-hour monitoring window
+
+4. CANARY rollout (flag ON for 5% of users)
+   └── Monitor error rates, latency, user behavior
+   └── Compare metrics: canary vs. baseline
+   └── 24-48 hour monitoring window
+   └── Advance only if all thresholds pass (see table below)
+
+5. GRADUAL increase (25% -> 50% -> 100%)
+   └── Same monitoring at each step
+   └── Ability to roll back to previous percentage at any point
+
+6. FULL rollout (flag ON for all users)
+   └── Monitor for 1 week
+   └── Clean up feature flag
+```
+
+### Rollout Decision Thresholds
+
+Use these thresholds to decide whether to advance, hold, or roll back at each stage:
+
+| Metric | Advance (green) | Hold and investigate (yellow) | Roll back (red) |
+|--------|-----------------|-------------------------------|-----------------|
+| Error rate | Within 10% of baseline | 10-100% above baseline | >2x baseline |
+| P95 latency | Within 20% of baseline | 20-50% above baseline | >50% above baseline |
+| Client JS errors | No new error types | New errors at <0.1% of sessions | New errors at >0.1% of sessions |
+| Business metrics | Neutral or positive | Decline <5% (may be noise) | Decline >5% |
+
+### When to Roll Back
+
+Roll back immediately if:
+- Error rate increases by more than 2x baseline
+- P95 latency increases by more than 50%
+- User-reported issues spike
+- Data integrity issues detected
+- Security vulnerability discovered
+
+## Monitoring and Observability
+
+### What to Monitor
+
+```
+Application metrics:
+├── Error rate (total and by endpoint)
+├── Response time (p50, p95, p99)
+├── Request volume
+├── Active users
+└── Key business metrics (conversion, engagement)
+
+Infrastructure metrics:
+├── CPU and memory utilization
+├── Database connection pool usage
+├── Disk space
+├── Network latency
+└── Queue depth (if applicable)
+
+Client metrics:
+├── Core Web Vitals (LCP, INP, CLS)
+├── JavaScript errors
+├── API error rates from client perspective
+└── Page load time
+```
+
+### Error Reporting
+
+```typescript
+// Set up error boundary with reporting
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    // Report to error tracking service
+    reportError(error, {
+      componentStack: info.componentStack,
+      userId: getCurrentUser()?.id,
+      page: window.location.pathname,
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
+    }
+    return this.props.children;
+  }
+}
+
+// Server-side error reporting
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  reportError(err, {
+    method: req.method,
+    url: req.url,
+    userId: req.user?.id,
+  });
+
+  // Don't expose internals to users
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  });
+});
+```
+
+### Post-Launch Verification
+
+In the first hour after launch:
+
+```
+1. Check health endpoint returns 200
+2. Check error monitoring dashboard (no new error types)
+3. Check latency dashboard (no regression)
+4. Test the critical user flow manually
+5. Verify logs are flowing and readable
+6. Confirm rollback mechanism works (dry run if possible)
+```
+
+## Rollback Strategy
+
+Every deployment needs a rollback plan before it happens:
+
+```markdown
+## Rollback Plan for [Feature/Release]
+
+### Trigger Conditions
+- Error rate > 2x baseline
+- P95 latency > [X]ms
+- User reports of [specific issue]
+
+### Rollback Steps
+1. Disable feature flag (if applicable)
+   OR
+1. Deploy previous version: `git revert <commit> && git push`
+2. Verify rollback: health check, error monitoring
+3. Communicate: notify team of rollback
+
+### Database Considerations
+- Migration [X] has a rollback: `npx prisma migrate rollback`
+- Data inserted by new feature: [preserved / cleaned up]
+
+### Time to Rollback
+- Feature flag: < 1 minute
+- Redeploy previous version: < 5 minutes
+- Database rollback: < 15 minutes
+```
+## See Also
+
+- For security pre-launch checks, see `references/security-checklist.md`
+- For performance pre-launch checklist, see `references/performance-checklist.md`
+- For accessibility verification before launch, see `references/accessibility-checklist.md`
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It works in staging, it'll work in production" | Production has different data, traffic patterns, and edge cases. Monitor after deploy. |
+| "We don't need feature flags for this" | Every feature benefits from a kill switch. Even "simple" changes can break things. |
+| "Monitoring is overhead" | Not having monitoring means you discover problems from user complaints instead of dashboards. |
+| "We'll add monitoring later" | Add it before launch. You can't debug what you can't see. |
+| "Rolling back is admitting failure" | Rolling back is responsible engineering. Shipping a broken feature is the failure. |
+
+## Red Flags
+
+- Deploying without a rollback plan
+- No monitoring or error reporting in production
+- Big-bang releases (everything at once, no staging)
+- Feature flags with no expiration or owner
+- No one monitoring the deploy for the first hour
+- Production environment configuration done by memory, not code
+- "It's Friday afternoon, let's ship it"
+
+## Required Checks
+
+Before deploying:
+
+- [ ] Pre-launch checklist completed (all sections green)
+- [ ] Feature flag configured (if applicable)
+- [ ] Rollback plan documented
+- [ ] Monitoring dashboards set up
+- [ ] Team notified of deployment
+
+After deploying:
+
+- [ ] Health check returns 200
+- [ ] Error rate is normal
+- [ ] Latency is normal
+- [ ] Critical user flow works
+- [ ] Logs are flowing
+- [ ] Rollback tested or verified ready
+
+## Verification
+After completing the skill, confirm:
+- [ ] Staged environments are verified via automated or manual checks before triggering the production push.
+- [ ] Active monitoring dashboards and error logs are observed for at least 15-30 minutes after release.
+- [ ] Rollback pathways and database rollbacks are checked and ready to be executed if incident thresholds are hit.

package/skills/memory/agent-memory/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: agent-memory
+description: Teaches agents how and when to use BrainRouter's memory engine (including Long-Term L1/L3, Short-Term Working Memory offloads, and Software Engineering-specific tools). Ensures the agent maintains context-awareness while proactively keeping context limits low.
+hints: |
+  - Extract if the user disables or opts out of memory capture (respect this as a hard rule).
+  - Note if the user prefers a specific recall strategy (keyword vs. hybrid).
+  - Capture if the user requests the agent to "forget" specific information.
+  - Note any sessions where the user explicitly asked for memory context to be surfaced.
+  - Ensure working memory offload is triggered for payloads >1,000 tokens.
+---
+
+# Agent Memory — Using BrainRouter Memory Tools
+
+## Overview
+
+BrainRouter's memory engine gives you persistent, cross-session awareness of the user. Use it consistently — an agent that doesn't recall context is worse than a stateless one because it appears to ignore the user.
+
+With the new Memory Systems, you have access to:
+1. **Long-Term Memory:** Retrieval-Augmented Generation (RAG) based on L1/L3 database entries.
+2. **L2 Pre-Warming Context (SNN):** Spiking Neural Network-inspired skill potentials. Invoking skills/tools charges potentials (up to `4.0`), while idle turns/time apply exponential decay. Active skill hints (potential `>= 0.3`) are dynamically injected under `<skill-prewarm>` system prompt blocks.
+3. **Short-Term Working Memory:** Active task canvases and reference-offloading to keep your prompt context clean and small during long conversations.
+4. **Software Engineering Tools:** Structured memory types (e.g., failed attempts, debug traces, file histories, task handovers).
+
+---
+
+## Workflow
+
+1. **Resolve and Start:** Call `mcp_brainrouter_resolve_session` at the beginning of a turn.
+2. **Context Setup & Pre-Warming:** Scan your system prompt for `<skill-prewarm>` XML tags and apply those pre-warmed instructions immediately. Then, invoke `memory_recall` and `memory_working_context` to inject long-term and short-term working state.
+3. **Payload Inspection:** Look up any referenced `nodeId` from the Mermaid canvas.
+4. **Execution & Offloading:** If executing a tool with output >1,000 tokens, offload via `memory_working_offload`.
+5. **Citational Signals:** Record memory citation outcomes via `memory_mark_cited`.
+6. **Passive or Manual Logging:** Capture the final turn state via passive hooks or manual `memory_capture_turn`. This turn logging spikes the activation potentials of related skills, keeping active context charged.
+
+## The Non-Negotiable Habits
+
+### 1. Before every response — recall memory & check working context
+- Call `memory_recall` to get relevant L1 memories and the user L3 persona.
+- If in a long-running debugging or coding session, call `memory_working_context` to fetch the high-level Mermaid task canvas and status.
+
+```typescript
+memory_recall({
+  sessionKey: "<conversation-id>", // ALWAYS USE THE CONVERSATION ID AS SESSION KEY
+  query: "<summary of current user message>",
+  activeSkill: "<current skill name, if any>"
+})
+```
+
+### 2. During execution — offload large payloads
+- Never paste large tool outputs, build logs, or code blocks (>1,000 tokens) back to the user or into your prompt. 
+- Proactively call `memory_working_offload` to save the payload to a reference file. The tool returns a short `nodeId` (e.g., `w1682390-a2ef`) to insert in your workspace context instead.
+
+```typescript
+memory_working_offload({
+  sessionKey: "<conversation-id>",
+  payload: "<large tool output stdout/stderr>",
+  title: "Build failure log",
+  kind: "tool_output"
+})
+```
+
+### 3. After every response — capture the turn (unless using passive hooks)
+- If passive lifecycle hooks are registered in the host environment, you do not need to call this.
+- If hooks are absent, call `memory_capture_turn` to store the conversation segment in L0.
+
+---
+
+## Memory Tool Taxonomy
+
+### 1. Long-Term Memory (RAG)
+| Tool | When to Call |
+| :--- | :--- |
+| `memory_recall` | **Before every response** — retrieves relevant context & persona. |
+| `memory_search` | When the automatically recalled context is missing specific past details. Supports `asOf` for point-in-time audits. |
+| `memory_contradictions` | Before making major architectural decisions or enforcing tech preferences. |
+| `memory_register_skill_hints` | When activating a skill for the first time in a new project. |
+
+### 2. Short-Term Working Memory (Context Reduction)
+| Tool | When to Call |
+| :--- | :--- |
+| `memory_working_context` | At the start of a turn to retrieve the active task state and Mermaid task canvas. |
+| `memory_working_offload` | To move a large payload out of the active prompt, returning a short `nodeId` placeholder. |
+| `memory_working_reset` | At the end of a session to completely flush working directories. |
+
+### 3. Software Engineering Traces
+| Tool | When to Call |
+| :--- | :--- |
+| `memory_task_state` / `_update` | To read/write structured progress, blockers, and next actions. |
+| `memory_failed_attempts` | To check what solutions have already been tried for a bug or problem area, preventing redundant work. |
+| `memory_file_history` | To query all historical memories and evidence attached to a specific file or symbol. |
+| `memory_debug_trace_save` | To save bug reproduction steps, root cause analysis, and fix summaries. |
+| `memory_handover` | To generate a compact continuation note with evidence links. |
+| `memory_verify` | To check a memory and update its confidence or status (active, superseded, archived). |
+
+## When to Use
+- Use at the start of every session or complex debugging task to load persona preferences, past engineering failed attempts, and high-level task status.
+- NOT for stateless operations (e.g. running single lint tests or querying a git commit list once).
+
+## What NOT to Do
+
+- **Never paste outputs >1,000 tokens** directly into conversation. Always offload them.
+- **Never skip `memory_recall`** before a response.
+- **Never repeat failed approaches** — check `memory_failed_attempts` when debugging.
+- **Limit memory tool calls** to a maximum of **3 per turn** to respect the latency budget.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| I don't need memory recall; I already know the context. | BrainRouter memory syncs user preferences and persona across multiple sessions. Skipping recall results in repetitive or off-track answers. |
+| The log is long, but I'll paste it anyway. | Large logs (exceeding 1000 tokens) blow up the prompt context window, wasting tokens and diluting relevant instructions. |
+
+## Red Flags
+- Committing giant files or pasting massive build outputs (>1,000 tokens) directly in the conversation.
+- Attempting a debug fix that has already been documented as a failure in `memory_failed_attempts`.
+- Disregarding user preferences retrieved from the L3 persona.
+
+## Verification
+
+After applying this skill, confirm:
+- [ ] `memory_recall` or `memory_working_context` was called to pull relevant developer configurations.
+- [ ] Large payloads or log blocks were offloaded via `memory_working_offload`.
+- [ ] Injected memory and Persona configurations were actively referenced in the output.