mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/database-sharding-advanced/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: database-sharding-advanced
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: database sharding advanced, resharding without downtime, cross-shard query, shard key selection, hotspot mitigation, shard rebalancing, consistent hashing shard, virtual shard, shard routing, shard-nothing architecture, geographic sharding, shard split
+compose: database-patterns
+---
+
+# Skill — Database Sharding (Advanced)
+
+## When this skill activates
+Any task involving horizontal database partitioning across multiple nodes,
+shard key selection, hotspot mitigation, resharding without downtime,
+cross-shard query strategies, or geographic data distribution.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Confirm sharding is necessary (vertical scaling exhausted? read replicas insufficient?).
+2. Select shard key using the three criteria: high cardinality + even distribution + query alignment.
+3. Plan cross-shard query strategy for necessary joins/aggregations.
+4. Design resharding approach (will need it eventually — plan now).
+
+### During implementation
+- Implement shard routing layer (application-level or proxy).
+- Use consistent hashing with virtual nodes for even distribution.
+- Denormalize data that would require frequent cross-shard joins.
+- Pre-compute aggregations that span shards.
+- Handle shard-local sequences (no global auto-increment).
+- Implement request routing that is transparent to application code.
+
+### After implementation
+- Verify even distribution across shards (no hotspots).
+- Test cross-shard queries perform within acceptable latency.
+- Validate resharding procedure in staging (dual-write → migrate → verify → cut).
+- Monitor per-shard metrics (query latency, storage, connections).
+- Load test at 2x expected traffic to validate shard capacity.
+
+## Shard Key Selection
+
+### Three Criteria (All Must Be Met)
+1. **High cardinality**: Many distinct values (user_id: good, country: bad).
+2. **Even distribution**: Values spread evenly across shards (random UUID: good, sequential ID: bad for hash).
+3. **Query alignment**: Most queries include the shard key (tenant_id if multi-tenant).
+
+### Common Shard Keys
+| Application Type | Good Shard Key | Why |
+|-----------------|---------------|-----|
+| Multi-tenant SaaS | tenant_id | All tenant data co-located |
+| Social media | user_id | Profile + posts together |
+| E-commerce | customer_id | Orders, cart, history together |
+| IoT | device_id | Time-series per device |
+| Gaming | player_id | Player state co-located |
+
+### Anti-Pattern Shard Keys
+- **Timestamp**: Creates hot shard (all writes to "current" shard).
+- **Sequential ID**: Skews to latest shard.
+- **Country/region**: Uneven (US shard overloaded, small countries under-utilized).
+- **Status field**: Low cardinality, uneven distribution.
+
+## Hotspot Mitigation
+
+### Techniques
+1. **Hash distribution**: Hash shard key before routing (spreads sequential keys).
+2. **Virtual shards**: Map to many virtual shards, assign groups to physical nodes.
+3. **Composite keys**: Combine shard key with secondary attribute (user_id + date_bucket).
+4. **Time-based rotation**: For time-series, rotate shard assignment periodically.
+5. **Write-behind aggregation**: Buffer hot-key writes, flush periodically.
+
+### Detecting Hotspots
+- Monitor per-shard write rate (>2x average = hotspot).
+- Monitor per-shard storage growth (uneven = distribution problem).
+- Monitor per-shard query latency (one slow = overloaded).
+
+## Resharding Without Downtime
+
+### The Double-Write Pattern
+```
+Phase 1: Dual-Write
+  - Write to both old shard AND new shard.
+  - Read from old shard.
+
+Phase 2: Backfill
+  - Copy historical data from old shard to new shard.
+  - Continue dual-writing.
+
+Phase 3: Verify
+  - Compare old and new shard data (row counts, checksums).
+  - Fix any discrepancies.
+
+Phase 4: Cutover
+  - Switch reads to new shard.
+  - Continue dual-writing briefly (safety net).
+
+Phase 5: Cleanup
+  - Stop writing to old shard.
+  - Archive/delete old shard data.
+```
+
+### Online Schema Change Tools
+- **gh-ost** (GitHub): Trigger-free, replication-based.
+- **pt-online-schema-change** (Percona): Trigger-based.
+- **Spirit**: For MySQL resharding specifically.
+
+### Rules
+- Never do big-bang migration (all-at-once = risky).
+- Always have rollback plan at every phase.
+- Verify data integrity between phases (checksums).
+- Run in staging first with production-like data volume.
+
+## Cross-Shard Queries
+
+### The Problem
+Once data is sharded, joins across shards are expensive (scatter-gather).
+
+### Strategies
+| Strategy | When to Use | Trade-off |
+|----------|-------------|-----------|
+| Denormalization | Frequent joins | Storage cost, write complexity |
+| Pre-computed aggregations | Analytics, dashboards | Staleness, compute cost |
+| Scatter-gather | Rare queries | Latency, complexity |
+| Global tables (replicated) | Small reference data | Replication lag |
+| Application-level joins | Low-volume cross-shard | Code complexity |
+
+### Denormalization Patterns
+- Store user name alongside every order (avoid cross-shard user lookup).
+- Embed category info in product documents.
+- Maintain per-shard aggregation counters (updated async).
+
+### When Scatter-Gather Is Acceptable
+- Admin queries (not user-facing, latency tolerant).
+- Batch jobs (run off-peak).
+- Infrequent search queries (use dedicated search index instead).
+
+## Consistent Hashing
+
+### How It Works
+1. Hash ring with positions 0 to 2^32.
+2. Each physical node gets multiple virtual nodes (tokens) on the ring.
+3. Data routes to first node clockwise from its hash position.
+4. Adding/removing node only affects adjacent range.
+
+### Virtual Nodes
+- Each physical node owns 100-256 virtual nodes.
+- More virtual nodes = more even distribution.
+- Adding a physical node: assign new virtual nodes, migrate only affected ranges.
+- Removing: redistribute its virtual nodes' ranges to neighbors.
+
+### Benefits Over Simple Modulo
+| Aspect | Modulo (hash % N) | Consistent Hashing |
+|--------|-------------------|-------------------|
+| Add node | ~100% data moves | ~1/N data moves |
+| Remove node | ~100% data moves | ~1/N data moves |
+| Distribution | Depends on hash | Even with virtual nodes |
+| Complexity | Simple | Moderate |
+
+## Geographic Sharding
+
+### Use Cases
+- Data sovereignty (EU data stays in EU).
+- Latency optimization (users read from nearest region).
+- Regulatory compliance (GDPR, data residency laws).
+
+### Patterns
+| Pattern | Reads | Writes | Consistency |
+|---------|-------|--------|-------------|
+| Write-local, read-local | Fast | Fast | Eventual (per-region) |
+| Write-primary, read-any | Fast | Slower (cross-region) | Strong for writes |
+| Multi-writer | Fast | Fast | Conflict resolution needed |
+
+### Conflict Resolution (Multi-Writer)
+- Last-write-wins (simple, data loss possible).
+- CRDTs (conflict-free, limited data types).
+- Application-level merge (complex, most flexible).
+- Operational transforms (collaborative editing).
+
+## Shard Routing
+
+### Routing Approaches
+1. **Application-level**: App knows shard map, routes directly.
+2. **Proxy layer**: Middleware (Vitess, ProxySQL) routes transparently.
+3. **Client library**: SDK handles routing, app unaware.
+
+### Shard Map
+```json
+{
+  "shards": [
+    {"id": 0, "range": "0000-3FFF", "host": "db-shard-0.internal"},
+    {"id": 1, "range": "4000-7FFF", "host": "db-shard-1.internal"},
+    {"id": 2, "range": "8000-BFFF", "host": "db-shard-2.internal"},
+    {"id": 3, "range": "C000-FFFF", "host": "db-shard-3.internal"}
+  ]
+}
+```
+
+## Self-check
+- [ ] Shard key meets all three criteria (cardinality, distribution, query alignment).
+- [ ] No hotspots detected (per-shard metrics balanced).
+- [ ] Cross-shard query strategy defined (denormalize, pre-compute, or scatter-gather).
+- [ ] Resharding procedure documented and tested in staging.
+- [ ] Consistent hashing with virtual nodes for even distribution.
+- [ ] Application transparent to sharding (routing layer handles it).
+- [ ] Per-shard monitoring (latency, storage, connections).
+- [ ] Rollback plan exists at every migration phase.
+- [ ] Geographic compliance verified if required.

package/.mindforge/skills/de-sloppify/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: de-sloppify
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: de-slop, cleanup pass, remove debug code, remove test slop, commented code, inconsistent naming, TODO hack, post-implementation cleanup, code hygiene, slop removal, dead code removal, polish pass
+---
+
+# Skill — De-Sloppify
+
+## When this skill activates
+
+After implementation is complete and working. This skill runs as a dedicated
+cleanup pass, separate from the implementation phase. Never during initial
+development — the implementer's job is to BUILD. De-sloppify runs AFTER to
+clean up the inevitable residue of rapid development.
+
+**Core principle**: No negative instructions to the implementer. Do not tell
+them "don't leave console.logs" or "don't forget to clean up." Let them build
+freely. This skill handles the cleanup as a distinct, focused phase.
+
+## Mandatory actions when this skill is active
+
+### Scan for all 5 slop categories
+
+#### Category 1 — Debug Code
+
+Detect and remove:
+
+- `console.log`, `console.debug`, `console.warn` (unless behind a debug flag)
+- `debugger` statements
+- `print()` statements not wrapped in a logging framework
+- `dump()`, `dd()`, `var_dump()` calls
+- Temporary `alert()` calls
+
+**Exception**: Logging that uses a structured logger (winston, pino, logging module)
+with appropriate log levels is NOT slop.
+
+#### Category 2 — Test Slop
+
+Detect and fix:
+
+- Skipped tests (`it.skip`, `xit`, `@pytest.mark.skip` without documented reason)
+- Commented-out test cases
+- Test-only backdoors in production code (e.g., `if (process.env.TEST) skip_auth()`)
+- Hardcoded test data left in source files (not in fixtures/factories)
+- `fit`, `fdescribe` (focused tests that exclude other tests)
+
+#### Category 3 — Commented Code Blocks
+
+Detect and remove:
+
+- Any block of 3+ consecutive commented lines that contain valid code
+- "Just in case" commented alternatives
+- Commented-out function bodies or class methods
+- Old implementations left as "reference"
+
+**Exception**: Comments that explain WHY (not what) are not slop, even if long.
+License headers are not slop.
+
+#### Category 4 — Inconsistent Naming
+
+Detect and fix:
+
+- camelCase/snake_case mixing within the same file
+- Inconsistent abbreviations (e.g., `btn` in one place, `button` in another)
+- Single-letter variables outside of tight loops or lambdas
+- Hungarian notation mixed with modern naming in the same module
+
+**Rule**: Match the dominant convention of the file. If the file is 80% camelCase,
+convert the remaining 20%.
+
+#### Category 5 — TODO Hacks
+
+Detect and evaluate:
+
+- TODOs that are actually shipped workarounds (not future work)
+- `// HACK:` comments with no linked ticket
+- `// FIXME:` that has been present for > 30 days (check git blame)
+- Temporary code with no expiration or tracking
+
+**Action**: Either fix the hack, or convert to a tracked issue with a link.
+Untracked TODOs in shipped code are technical debt that compounds silently.
+
+### Commit discipline
+
+- Each category fix is a SEPARATE atomic commit
+- Commit message format: `chore(cleanup): remove [category] slop from [scope]`
+- Never combine cleanup across categories in a single commit
+- This enables easy revert if any cleanup accidentally changes behavior
+
+### Verification
+
+After ALL cleanup is complete:
+
+- Run the full test suite
+- Verify no behavior change (tests pass identically)
+- If any test fails after cleanup, the cleanup introduced a regression — revert that commit
+- Compare test output before/after: same pass count, same coverage
+
+### Output
+
+Write `CLEANUP-REPORT.md` to `.planning/` containing:
+
+- Summary: total issues found and fixed per category
+- Before/after counts for each category
+- Files touched per category
+- Any items intentionally left (with justification)
+- Test results: pass/fail count before and after cleanup
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I scan for ALL 5 categories (debug, test slop, commented code, naming, TODOs)?
+- [ ] Did I commit each category fix as a separate atomic commit?
+- [ ] Did I verify tests still pass after every cleanup commit?
+- [ ] Did I confirm no behavior change was introduced?
+- [ ] Did I write CLEANUP-REPORT.md with before/after counts?
+- [ ] Did I leave justified exceptions documented (not silently skipped)?

package/.mindforge/skills/defense-in-depth/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: defense-in-depth
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: defense in depth, layered validation, entry point guard, business logic guard, environment guard, debug instrumentation, validation layer, multi-layer security, input boundary, trust boundary guard, defensive coding, guard clause pattern
+compose:
+  - security-review
+---
+
+# Skill — Defense in Depth
+
+## When this skill activates
+
+Any task that introduces or modifies code handling external input, enforcing
+business rules, managing environment-specific behavior, or adding observability.
+Activate whenever you are building anything that crosses a trust boundary or
+touches validation logic at any layer of the stack.
+
+## Mandatory actions when this skill is active
+
+Four independent validation layers must be applied. Each layer is autonomous:
+failure or absence in one layer does NOT exempt the others.
+
+### Layer 1 — Entry Point Validation
+
+Apply at the API boundary (route handler, CLI argument parser, event handler):
+
+- Schema validation using a strict schema library (Zod, Joi, Pydantic, etc.)
+- Type coercion with explicit rules (string-to-number only where defined)
+- Reject invalid input immediately with a 400-level response
+- Never pass unvalidated input deeper into the system
+- Strip unknown fields; never allow arbitrary pass-through
+
+### Layer 2 — Business Logic Guards
+
+Apply inside domain/service layer functions:
+
+- Assert domain invariants (e.g., balance >= 0, state transitions are valid)
+- State machine guards: verify current state allows the requested transition
+- Authorization assertions: re-check permissions at the service boundary
+- Fail loudly with descriptive errors when invariants are violated
+- Never rely solely on entry point validation; business logic must self-protect
+
+### Layer 3 — Environment Guards
+
+Apply environment-specific behavior through configuration, not conditionals:
+
+- **Production**: strict mode, no debug endpoints exposed, minimal error detail
+  in responses, all logging structured and shipped to aggregator
+- **Staging**: production-like but with extended logging and feature flags
+- **Test**: relaxed logging, verbose error output, mock services allowed
+- Guard debug endpoints behind environment checks (never reachable in prod)
+- Validate required environment variables at startup; crash early if missing
+
+### Layer 4 — Debug Instrumentation
+
+Apply observability that aids debugging without compromising security:
+
+- Structured logging with consistent fields (timestamp, traceId, userId, action)
+- Trace IDs propagated through all layers (generate at entry point, pass down)
+- Development assertions (enabled in test/dev, compiled out or disabled in prod)
+- Never log secrets, tokens, passwords, or full request bodies in production
+- Include enough context to reproduce issues from logs alone
+
+## Independence principle
+
+Each layer must function correctly even if the others are absent. This means:
+
+- Business logic must not assume entry point already validated
+- Environment guards must not assume instrumentation is active
+- Instrumentation must not assume any specific validation has occurred
+- Entry point validation must not assume business logic will catch overflows
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I validate at the entry point (schema, types, rejection of invalid)?
+- [ ] Did I add business logic guards (invariants, state checks, auth assertions)?
+- [ ] Did I implement environment guards (prod strict, test relaxed, no debug in prod)?
+- [ ] Did I include debug instrumentation (structured logs, trace IDs, assertions)?
+- [ ] Are all four layers independent (no layer relies on another for correctness)?
+- [ ] Did I verify that secrets are never exposed in any logging layer?

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

@@ -0,0 +1,123 @@
+---
+name: delegation-patterns
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: delegation engineering, task decomposition team, ownership assignment, accountability framework, work distribution, delegation decision matrix, scope assignment, technical project delegation, parallel workstream assignment, responsibility matrix, RACI technical, decision authority
+---
+
+# Delegation Patterns
+
+## When this skill activates
+
+This skill activates when decomposing tasks for teams, assigning ownership, distributing work across engineers, defining accountability frameworks, or delegating technical projects. It applies to tech leads, engineering managers, and senior engineers responsible for coordinating team execution.
+
+## Mandatory actions when this skill is active
+
+### Before delegating
+
+1. **Assess task complexity and risk** — Low-complexity, low-risk tasks can be delegated broadly. High-complexity or high-risk tasks require senior engineers or your direct involvement.
+2. **Match task to skill level** — Don't assign senior-level architectural work to juniors. Don't assign junior-level bug fixes to staff engineers (unless it's urgent). Mismatched delegation wastes talent and causes frustration.
+3. **Verify availability and capacity** — Don't assume engineers have bandwidth. Check current workload, upcoming PTO, and competing priorities before assigning work.
+4. **Define success criteria explicitly** — What does "done" look like? Ambiguous success criteria lead to misalignment. Be specific: "Tests pass, code reviewed, deployed to staging."
+
+### During delegation
+
+#### Task Decomposition for Teams
+
+- **Break large projects into independent workstreams** — Identify natural boundaries (frontend vs backend, service A vs service B, feature 1 vs feature 2). Minimize dependencies between workstreams to enable parallel execution.
+- **Size tasks to 1-3 day chunks** — Tasks larger than 3 days are hard to estimate and easy to get stuck on. Smaller tasks improve velocity and visibility.
+- **Create a dependency graph** — Visualize which tasks block others. Critical path tasks need the strongest engineers. Non-blocking tasks can be assigned to juniors or done in parallel.
+- **Avoid over-fragmentation** — Breaking a 2-week project into 50 tiny tasks creates coordination overhead. Find the balance: small enough to track, large enough to be meaningful.
+
+#### Ownership Assignment
+
+- **Use the DRI (Directly Responsible Individual) model** — Every task has exactly one owner. Shared ownership is no ownership. If two people are responsible, neither is.
+- **Clarify ownership boundaries** — DRI owns the outcome, not just the execution. They are accountable for delivery, quality, and communication. Support them, but don't take the ownership back.
+- **Match ownership to growth goals** — If an engineer wants to grow into system design, give them a project that requires design work. Delegation is a growth lever.
+- **Avoid always delegating to the same high performers** — Spreading work across the team builds depth and prevents burnout. High performers need growth opportunities, not just more work.
+
+#### Delegation Decision Matrix
+
+Use this framework to decide who gets what:
+
+| Task Type | Delegate To | Reasoning |
+|-----------|-------------|-----------|
+| Low complexity, low risk | Junior engineer | Growth opportunity, low downside |
+| High complexity, low risk | Mid-level engineer | Stretch assignment, safe to experiment |
+| Low complexity, high risk | Senior engineer | Minimize risk, fast execution |
+| High complexity, high risk | Staff/Principal or yourself | Critical tasks need top talent |
+| Repetitive toil | Automate or rotate | Don't delegate to the same person forever |
+| Cross-team coordination | Tech lead or manager | Requires influence and context |
+
+#### Accountability Framework
+
+- **Define RACI roles explicitly** — For every project or decision:
+  - **Responsible**: Who does the work?
+  - **Accountable**: Who owns the outcome? (Only one person)
+  - **Consulted**: Who provides input?
+  - **Informed**: Who needs to know?
+- **Document RACI in project kickoffs** — Put it in the project doc, share it with the team. Ambiguous accountability causes dropped work and finger-pointing.
+- **Check-ins, not micromanagement** — Set a cadence (daily standup, weekly sync) but trust the DRI to execute. If you're in the weeds every day, you didn't delegate properly.
+
+#### Work Distribution Strategies
+
+**1. Balanced Distribution (Default)**
+- **Goal**: Spread work evenly across the team.
+- **When to use**: Routine feature work, stable team, predictable roadmap.
+- **Pitfall**: Can over-distribute and prevent deep focus. Balance with ownership zones (next pattern).
+
+**2. Ownership Zones (Area-Based)**
+- **Goal**: Each engineer owns 1-2 services or features end-to-end.
+- **When to use**: Mature team, well-defined boundaries, need for deep expertise.
+- **Benefit**: Engineers become experts in their zone, reducing ramp-up time and increasing autonomy.
+- **Pitfall**: Creates silos. Mitigate with code reviews across zones and occasional rotation.
+
+**3. Swarming (All-Hands-On-Deck)**
+- **Goal**: Entire team focuses on one critical project.
+- **When to use**: High-priority launch, critical bug, tight deadline.
+- **Benefit**: Fast execution, high alignment.
+- **Pitfall**: Interrupts other work. Use sparingly.
+
+**4. Rotation (Shared Responsibility)**
+- **Goal**: Engineers rotate through on-call, support, or maintenance tasks.
+- **When to use**: Prevent burnout, build shared context, avoid "that one person" syndrome.
+- **Benefit**: Spreads toil evenly, prevents knowledge silos.
+- **Pitfall**: Context switching overhead. Set rotation cadence (weekly, bi-weekly) to minimize thrash.
+
+#### Delegation Communication
+
+- **Use structured task handoffs** — When delegating, provide:
+  - **Context**: Why are we doing this? What's the business value?
+  - **Scope**: What's in scope, what's out of scope?
+  - **Success criteria**: How will we know it's done?
+  - **Resources**: Who can help? What docs are relevant?
+  - **Deadline**: When is it due?
+  - **Check-in cadence**: How often should we sync?
+- **Empower, don't prescribe** — Tell them what to achieve, not how to do it. Let them figure out the approach (unless they ask for guidance).
+- **Clarify decision authority** — Can they decide on implementation details? Do they need approval for architectural choices? Make it explicit.
+
+#### Monitoring Delegation Effectiveness
+
+- **Track task completion rate** — If tasks are frequently late or incomplete, you're either over-delegating, under-resourcing, or assigning to the wrong people.
+- **Measure rework rate** — If delegated work requires significant rework, either the success criteria were unclear or the engineer wasn't ready for the task.
+- **Check engineer satisfaction** — Periodically ask: "Do you feel over/under-utilized? Are you getting enough growth opportunities?" Course-correct before burnout or attrition.
+
+### After delegating
+
+- **Verify understanding** — After assigning work, ask the engineer to summarize: "What's the goal? What's the first step?" Misalignment is common. Catch it early.
+- **Set check-in cadence** — For junior engineers: daily check-ins. For mid-level: every 2-3 days. For senior: weekly or as-needed. Adjust based on risk and autonomy.
+- **Unblock actively** — If the engineer is stuck, intervene. Don't wait for them to ask. Watch for signs: long periods of silence, lack of progress updates, frustrated messages.
+- **Give credit publicly** — When the work is done, recognize the engineer publicly (in team meetings, Slack, all-hands). Delegation without recognition demoralizes.
+- **Conduct retrospectives** — After major projects, ask: "What went well? What would we do differently next time?" Improve your delegation process over time.
+
+## Self-check before task completion
+
+- [ ] Task complexity and risk are assessed before assigning
+- [ ] Task is matched to engineer's skill level and growth goals
+- [ ] Success criteria are explicit and documented
+- [ ] Ownership is assigned to exactly one DRI (Directly Responsible Individual)
+- [ ] RACI roles are defined (Responsible, Accountable, Consulted, Informed)
+- [ ] Task decomposition creates independent workstreams to enable parallel execution
+- [ ] Delegation handoff includes context, scope, success criteria, resources, and deadline
+- [ ] Check-in cadence is set and followed (daily for juniors, weekly for seniors)

package/.mindforge/skills/dependency-management/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: dependency-management
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: dependency management, version resolution, lockfile strategy, dep hoisting, peer dependency, transitive audit, dependency graph, version conflict, dependency update, semver resolution, dependency pruning, phantom dependency
+compose: supply-chain-security
+---
+
+# Skill — Dependency Management
+
+## When this skill activates
+Any task involving package management, version conflicts, lockfile strategies,
+dependency auditing, update workflows, or supply chain concerns.
+
+## Mandatory actions when this skill is active
+
+### Before modifying dependencies
+1. Understand the current dependency graph and any existing conflicts.
+2. Check if the new dependency is actively maintained (last commit, open issues).
+3. Verify license compatibility with the project.
+
+### Lockfiles
+
+- **Always commit lockfiles** (package-lock.json, yarn.lock, pnpm-lock.yaml).
+- **CI must use --frozen-lockfile** (or equivalent) to prevent drift.
+- **Review lockfile changes in PRs** — unexpected transitive additions are a signal.
+- Never manually edit lockfiles — use the package manager to resolve.
+- If lockfile conflicts in merge: delete lockfile, reinstall, commit fresh.
+
+### Version resolution by package manager
+
+**npm (nearest-wins, hoisted):**
+- Hoists shared deps to root node_modules.
+- Different versions of same package can coexist in nested node_modules.
+- Potential for phantom dependencies (using undeclared deps that happen to be hoisted).
+
+**pnpm (strict, isolated):**
+- Symlink-based, no hoisting by default.
+- Catches phantom dependencies immediately.
+- Content-addressable store saves disk space.
+- Recommended for monorepos and strict environments.
+
+**yarn (hoisted, PnP optional):**
+- Classic: hoisted like npm.
+- PnP (Plug'n'Play): no node_modules, direct resolution via .pnp.cjs.
+- PnP is strict but has ecosystem compatibility challenges.
+
+### Peer dependencies
+
+- **Declare compatibility range** in your library's peerDependencies.
+- **Do not install** peer deps in the library — the consuming application does.
+- Use `peerDependenciesMeta` to mark optional peers.
+- Test against the minimum AND maximum of your declared peer range.
+
+### Phantom dependencies
+
+- Dependencies you use in code but did not explicitly declare in package.json.
+- They work by accident (hoisted from a transitive dep).
+- **Detection:** use pnpm (strict mode) or run `depcheck`.
+- **Fix:** add to dependencies explicitly or remove the usage.
+
+### Update strategy
+
+**Automated (Dependabot/Renovate):**
+- Configure for weekly minor/patch updates.
+- Group related deps (e.g., all @testing-library/* together).
+- Auto-merge if CI passes for patch updates.
+- Require manual review for major bumps.
+
+**Manual quarterly major bumps:**
+- Schedule quarterly "dependency day" for major version upgrades.
+- Read changelogs and migration guides before upgrading.
+- Upgrade one major dep at a time, verify tests pass.
+
+### Pruning
+
+- **Find unused deps:** run `depcheck` or `knip` regularly.
+- **Remove aggressively** — fewer deps = smaller attack surface + faster installs.
+- Check for lighter alternatives (e.g., date-fns instead of moment).
+- Evaluate if a dep is worth it: if you only use one function, inline it.
+
+### Monorepo-specific
+
+- Use workspace protocols (workspace:*) for internal packages.
+- Hoist shared devDependencies to root.
+- Keep runtime deps in each package's own package.json.
+- Use changesets or lerna for coordinated versioning.
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?