skillstore-cli 1.0.0

package/data/shared/framework/skills/backend-development/references/observability-resilience.md

@@ -0,0 +1,155 @@
+# Observability & Resilience
+
+## Circuit Breaker Pattern
+
+Prevent cascading failures by stopping calls to a failing service.
+
+```typescript
+import CircuitBreaker from 'opossum';
+
+const breaker = new CircuitBreaker(callExternalService, {
+  timeout: 3000,                   // Trip if call exceeds 3s
+  errorThresholdPercentage: 50,    // Trip if 50% fail
+  resetTimeout: 10000,             // Retry after 10s (half-open)
+  volumeThreshold: 10,             // Min requests before tripping
+});
+
+breaker.fallback(() => getCachedResponse());
+const result = await breaker.fire(requestParams);
+```
+
+**States:** Closed (normal) → Open (all rejected, fallback used) → Half-Open (test call) → Closed if test succeeds.
+
+---
+
+## Distributed Tracing (OpenTelemetry)
+
+### Setup
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+
+const sdk = new NodeSDK({
+  resource: new Resource({ [ATTR_SERVICE_NAME]: 'order-service' }),
+  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4318/v1/traces' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+```
+
+### Span Creation & Context Propagation
+
+```typescript
+import { trace, context, propagation, SpanStatusCode } from '@opentelemetry/api';
+const tracer = trace.getTracer('order-service');
+
+async function processOrder(order: Order) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    span.setAttribute('order.id', order.id);
+    // Manual propagation (e.g., for message queues):
+    const carrier: Record<string, string> = {};
+    propagation.inject(context.active(), carrier);
+    await queue.publish('orders', { ...order, _traceContext: carrier });
+    span.end();
+  });
+}
+```
+
+---
+
+## Health Checks (Kubernetes)
+
+```yaml
+spec:
+  containers:
+    - name: api
+      livenessProbe:          # Restart if failing — never check dependencies here
+        httpGet: { path: /healthz/live, port: 8080 }
+        periodSeconds: 15
+        failureThreshold: 3
+      readinessProbe:         # Remove from LB if failing — checks DB, cache, downstream
+        httpGet: { path: /healthz/ready, port: 8080 }
+        periodSeconds: 10
+        failureThreshold: 2
+      startupProbe:           # Block other probes until app finishes init
+        httpGet: { path: /healthz/startup, port: 8080 }
+        periodSeconds: 5
+        failureThreshold: 30
+```
+
+---
+
+## Structured Logging Pipeline
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: { level(label) { return { level: label }; } },
+  base: { service: 'order-service', environment: process.env.NODE_ENV },
+});
+
+logger.info({ orderId: '123', duration: 45 }, 'Order processed');
+```
+
+### Collection (Vector)
+
+```toml
+[sources.app_logs]
+type = "file"
+include = ["/var/log/app/*.log"]
+
+[transforms.parse]
+type = "remap"
+inputs = ["app_logs"]
+source = '. = parse_json!(.message)'
+
+[sinks.loki]
+type = "loki"
+inputs = ["parse"]
+endpoint = "http://loki:3100"
+labels = { service = "{{ service }}", level = "{{ level }}" }
+```
+
+**Pipeline:** App (JSON stdout) → Vector/Fluentd → Loki/Elasticsearch → Grafana/Kibana
+
+---
+
+## RED Metrics & Golden Signals
+
+**RED Method** (request-driven services):
+- **Rate** — Requests/sec (`http_requests_total`)
+- **Errors** — Failed requests/sec (`http_requests_total{status=~"5.."}`)
+- **Duration** — Latency histogram (`http_request_duration_seconds`)
+
+**Golden Signals** (Google SRE): Latency, Traffic, Errors, Saturation (CPU%, memory%, queue depth).
+
+---
+
+## Alerting Strategy
+
+| Severity | Response | Example | Action |
+|---|---|---|---|
+| **P1** | 15 min | Service down, data loss | Page on-call, incident bridge |
+| **P2** | 1 hour | Error rate > 5%, p99 > 2s | Page during business hours |
+| **P3** | 4 hours | Disk > 80%, elevated errors | Slack, next available engineer |
+| **P4** | Next day | Deprecation warnings | Auto-create ticket |
+
+**Rules:** Alert on symptoms, not causes. Use multi-window burn-rate alerts. Every alert needs a runbook. Suppress downstream when upstream is alerting.
+
+---
+
+## Graceful Degradation
+
+**Fallback strategies:**
+- **Cache fallback** — Serve stale data when upstream is down
+- **Default response** — Return safe defaults (empty list, default config)
+- **Feature toggle** — Disable non-critical features under load
+- **Read-only mode** — Allow reads, reject writes during partial outages
+
+**Priorities:** Map critical vs non-critical paths. Set timeouts on every external call. Use bulkheads (separate pools per dependency). Test degraded modes with chaos engineering.

package/data/shared/framework/skills/backend-development/references/troubleshooting.md

@@ -0,0 +1,199 @@
+# Backend Troubleshooting Guide
+
+## Connection Pool Exhaustion
+
+**Symptoms:** Application hangs on database queries, errors like "too many connections", "connection pool timeout", latency spikes under moderate load.
+
+**Diagnosis:**
+```sql
+-- PostgreSQL: check active connections
+SELECT count(*), state FROM pg_stat_activity GROUP BY state;
+
+-- Check max connections setting
+SHOW max_connections;
+
+-- Find long-running queries holding connections
+SELECT pid, now() - pg_stat_activity.query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE state != 'idle'
+ORDER BY duration DESC;
+```
+
+**Fix patterns:**
+1. **Pool size too small** — Increase `max` in pool config. Rule of thumb: `pool_size = (core_count * 2) + disk_count`.
+2. **Connections not released** — Missing `.release()` or `finally` block after query.
+   - Fix: Always use try/finally or connection wrapper that auto-releases.
+3. **Long-running transactions** — Holding connections for external API calls.
+   - Fix: Fetch external data first, then open transaction only for DB writes.
+4. **Idle connection timeout not set** — Add `idleTimeoutMillis` (e.g., 30000ms) to pool config.
+
+## Node.js Memory Leaks
+
+**Diagnosis workflow:**
+```bash
+# Start with inspector
+node --inspect --max-old-space-size=512 app.js
+
+# Take heap snapshots via Chrome DevTools
+# chrome://inspect → Open dedicated DevTools
+
+# CLI heap dump (production-safe)
+kill -USR2 <pid>  # If using heapdump module
+
+# Monitor memory over time
+node -e "setInterval(() => console.log(process.memoryUsage()), 5000)"
+```
+
+**Common causes:**
+1. **Global caches without eviction** — Objects accumulate in module-level Maps/Sets.
+   - Fix: Use LRU cache (`lru-cache` package) with maxSize and TTL.
+2. **Event emitter listeners accumulating** — `emitter.on()` called repeatedly without `off()`.
+   - Fix: Use `once()` where possible, track and remove listeners on cleanup.
+3. **Closures in request handlers** — Large objects captured in closure scope.
+   - Fix: Nullify references after use, avoid closing over request/response objects in async callbacks.
+4. **Unreferenced timers** — `setInterval` created per request without `clearInterval`.
+   - Fix: Track timer IDs, clear on connection close.
+
+**Heap snapshot comparison:**
+1. Take snapshot A (baseline).
+2. Run load test or wait for traffic.
+3. Take snapshot B.
+4. In DevTools: select snapshot B → Comparison view → sort by "Size Delta".
+
+## 502/504 Gateway Timeout Tracing
+
+**502 Bad Gateway — upstream server returned invalid response:**
+1. Check if the application process is running: `ps aux | grep node`.
+2. Check application logs for crashes or uncaught exceptions.
+3. Verify the upstream port matches the proxy config (nginx/ALB).
+4. Check health check endpoint: `curl -v http://localhost:PORT/health`.
+
+**504 Gateway Timeout — upstream did not respond in time:**
+1. Identify the slow endpoint from access logs.
+2. Check database query times for that endpoint.
+3. Verify timeout chain: client (30s) < proxy (60s) < app server (90s).
+4. Look for external API calls without timeouts.
+
+**Fix patterns:**
+- Set explicit timeouts on all outbound HTTP calls: `fetch(url, { signal: AbortSignal.timeout(5000) })`.
+- Configure proxy timeouts: `proxy_read_timeout 60s;` in nginx.
+- Add request-level timeout middleware: kill requests exceeding SLA.
+- Implement circuit breaker for flaky upstream dependencies.
+
+## Database Deadlocks Detection and Prevention
+
+**Detection:**
+```sql
+-- PostgreSQL: find blocked and blocking queries
+SELECT blocked.pid AS blocked_pid,
+       blocked.query AS blocked_query,
+       blocking.pid AS blocking_pid,
+       blocking.query AS blocking_query
+FROM pg_stat_activity blocked
+JOIN pg_locks bl ON bl.pid = blocked.pid
+JOIN pg_locks kl ON kl.locktype = bl.locktype
+  AND kl.database IS NOT DISTINCT FROM bl.database
+  AND kl.relation IS NOT DISTINCT FROM bl.relation
+  AND kl.page IS NOT DISTINCT FROM bl.page
+  AND kl.tuple IS NOT DISTINCT FROM bl.tuple
+  AND kl.pid != bl.pid
+JOIN pg_stat_activity blocking ON kl.pid = blocking.pid
+WHERE NOT bl.granted;
+```
+
+**Prevention patterns:**
+1. **Consistent lock ordering** — Always acquire locks on tables/rows in the same order across all transactions.
+2. **Short transactions** — Minimize the work done inside a transaction.
+3. **Use `SELECT ... FOR UPDATE SKIP LOCKED`** for queue-like patterns.
+4. **Set lock timeout**: `SET lock_timeout = '5s';` to fail fast instead of deadlocking.
+5. **Retry with backoff** — Catch deadlock errors (code 40P01) and retry the transaction.
+
+## JWT / Auth Token Debugging Checklist
+
+**Token rejected — systematic diagnosis:**
+1. Decode the token: `echo "<token>" | cut -d. -f2 | base64 -d 2>/dev/null | jq .`
+2. Check `exp` claim — is it expired? Compare with `date +%s`.
+3. Check `iss` (issuer) — does it match your auth server?
+4. Check `aud` (audience) — does it match your API's expected audience?
+5. Verify signature — is the server using the correct public key / secret?
+6. Check clock skew — is the server clock synchronized? (>30s drift causes failures).
+
+**Common issues:**
+- **Token works locally but not in production** — Different JWT secrets in environments.
+- **Token expires too fast** — Short `exp`, no refresh token mechanism.
+- **JWKS endpoint unreachable** — Auth server DNS or firewall issue.
+- **"Algorithm none" vulnerability** — Ensure server rejects `alg: none`.
+
+## Rate Limiting Misconfiguration Symptoms
+
+**Symptoms:** Legitimate users get 429 errors, rate limits don't apply to abusers, inconsistent behavior across instances.
+
+**Diagnosis:**
+1. Check rate limit headers in response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+2. Verify the key used for rate limiting — IP? User ID? API key?
+3. If behind a load balancer: is each instance counting independently? (Need shared store like Redis.)
+
+**Fix patterns:**
+- **Shared store required** — Use Redis with `INCR` + `EXPIRE` for distributed rate limiting.
+- **Wrong client IP** — Behind proxy, use `X-Forwarded-For` header (validate trust chain).
+- **Missing bypass for health checks** — Internal health probes consuming rate limit quota.
+- **Sliding window vs fixed window** — Fixed window allows burst at boundary; use sliding window for smoother limiting.
+
+## Container OOM Kills
+
+**Symptoms:** Container restarts with exit code 137, `dmesg` shows "Out of memory: Killed process".
+
+**Diagnosis:**
+```bash
+# Check container memory usage
+docker stats <container_id>
+
+# Check OOM kill events
+dmesg | grep -i "oom\|killed"
+
+# Kubernetes: check pod events
+kubectl describe pod <pod_name> | grep -A5 "Last State"
+kubectl top pod <pod_name>
+
+# Node.js: log memory at intervals
+node -e "setInterval(() => { const m = process.memoryUsage(); console.log('RSS:', (m.rss/1024/1024).toFixed(1), 'MB, Heap:', (m.heapUsed/1024/1024).toFixed(1), 'MB'); }, 10000)"
+```
+
+**Fix patterns:**
+1. **Set Node.js heap limit below container limit** — `--max-old-space-size=384` for a 512MB container (leave room for native memory).
+2. **Stream large data** — Don't load entire files/datasets into memory; use Node.js streams.
+3. **Limit concurrency** — Use `p-limit` or similar to cap parallel async operations.
+4. **Right-size the container** — Profile actual usage and set memory request/limit accordingly.
+
+## Event Loop Blocking Diagnosis
+
+**Symptoms:** All requests slow down simultaneously, health checks timeout, high latency with low CPU usage.
+
+**Detection:**
+```javascript
+// Detect event loop delays
+const { monitorEventLoopDelay } = require('perf_hooks');
+const h = monitorEventLoopDelay({ resolution: 20 });
+h.enable();
+setInterval(() => {
+  console.log(`Event loop p99: ${(h.percentile(99) / 1e6).toFixed(1)}ms`);
+  h.reset();
+}, 5000);
+
+// Blocked-at module (development only)
+// npm install blocked-at
+const blocked = require('blocked-at');
+blocked((time, stack) => {
+  console.log(`Blocked for ${time}ms`, stack);
+});
+```
+
+**Common blockers:**
+1. **Synchronous file operations** — `fs.readFileSync`, `fs.writeFileSync` in request handlers.
+   - Fix: Use async versions `fs.promises.readFile`.
+2. **JSON.parse/stringify on large payloads** — Blocks for 100ms+ on multi-MB objects.
+   - Fix: Use streaming JSON parser (`stream-json`) or move to worker thread.
+3. **CPU-intensive computation** — Crypto, image processing, data transformation.
+   - Fix: Offload to `worker_threads` or a separate microservice.
+4. **DNS resolution** — `dns.lookup` is synchronous by default in libuv.
+   - Fix: Use `dns.resolve` (async) or configure DNS caching.

package/data/shared/framework/skills/codebase-analysis/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: codebase-analysis
+description: Systematic codebase exploration — dependency mapping, architecture assessment, tech debt inventory, impact analysis for informed decision-making
+---
+
+# Codebase Analysis
+
+## Triggers
+
+Activate this skill when:
+- Joining a new project and need to understand the codebase
+- Before major refactoring to assess scope and risk
+- Performing impact analysis before significant changes
+- Conducting a tech debt review or sprint planning
+- Running a dependency audit (security, outdated, license)
+- Documenting architecture for onboarding or decision records
+
+## Process
+
+### 1. Scope Definition
+- Clarify what to analyze: full codebase, specific package, or change blast radius
+- Identify stakeholders and what decisions the analysis will inform
+- Set time-box — analysis should enable action, not become a project itself
+
+### 2. Structure Scan
+- Map directory layout to identify architectural pattern (layered, feature-based, domain-driven)
+- Identify entry points: HTTP handlers, CLI commands, event consumers, cron jobs
+- Catalog build configuration: bundlers, compilers, CI/CD pipelines
+- Note framework and language versions
+
+### 3. Dependency Mapping
+- Generate module dependency graph (internal imports)
+- Detect circular dependencies and tightly coupled modules
+- Audit external dependencies: outdated, vulnerable, abandoned, license issues
+- Map service-to-service and API dependencies
+
+### 4. Quality Assessment
+- Measure complexity hotspots (cyclomatic/cognitive complexity × change frequency)
+- Review test coverage distribution across modules
+- Count linter warnings, TODO/FIXME/HACK markers
+- Assess type coverage and strict mode adoption
+- Identify dead code and unused exports
+
+### 5. Report Generation
+- Summarize architecture with a clear overview
+- List findings grouped by category with severity scores
+- Prioritize recommendations: quick wins first, then planned improvements
+- Include evidence (file paths, metrics, examples) for every finding
+
+## Quick Reference
+
+| Analysis Goal | Technique | Key Tool/Command |
+|---|---|---|
+| Understand structure | Directory analysis | `tree -L 3 -d`, `find . -name 'index.*'` |
+| Map dependencies | Import graph traversal | `madge --image`, `go mod graph` |
+| Find dead code | Unused export detection | `knip`, `ts-prune` |
+| Measure complexity | Cyclomatic complexity | `eslint --rule complexity`, `radon` |
+| Detect hotspots | Git change frequency | `git log --format='%H' --follow <file>` |
+| Audit packages | Outdated/vulnerable check | `npm outdated`, `npm audit` |
+| Assess test gaps | Coverage by module | `jest --coverage`, `coverage.py` |
+| Trace request flow | Entry point tracing | Read handler → service → repository |
+| Quantify tech debt | Marker grep + scoring | `grep -rn 'TODO\|FIXME\|HACK'` |
+
+## References
+
+- [Analysis Techniques](references/analysis-techniques.md) — directory analysis, complexity metrics, hotspot detection, entry point tracing
+- [Dependency Mapping](references/dependency-mapping.md) — import graphs, circular dependency resolution, external audit, upgrade strategy
+- [Tech Debt Assessment](references/tech-debt-assessment.md) — debt taxonomy, severity scoring, discovery checklist, remediation prioritization
+
+## Assets
+
+- [Sample Output](assets/sample-output.md) — complete analysis report for a Node.js + React monorepo

package/data/shared/framework/skills/codebase-analysis/assets/sample-output.md

@@ -0,0 +1,263 @@
+# Codebase Analysis Report: TaskFlow
+
+**Project**: TaskFlow — Task management application
+**Date**: 2026-03-15
+**Scope**: Full codebase analysis
+**Analyst**: Engineering Team
+
+---
+
+## 1. Architecture Overview
+
+### Project Structure
+
+```
+taskflow/
+  packages/
+    api/              # Express.js REST API (Node.js 18)
+    web/              # React 18 + Vite SPA
+    shared/           # Shared types, validation, utilities
+  infrastructure/
+    docker/           # Docker Compose for local dev
+    terraform/        # AWS infrastructure (ECS, RDS, S3)
+  docs/
+  scripts/            # Build, deploy, migration scripts
+```
+
+### Architecture Style
+
+**API** — Layered architecture:
+- `routes/` → `controllers/` → `services/` → `repositories/`
+- Clear separation of concerns
+- Dependency injection via `tsyringe`
+
+**Web** — Feature-based structure:
+- `features/auth/`, `features/tasks/`, `features/projects/`
+- Each feature contains components, hooks, and API calls
+- Shared components in `shared/ui/`
+
+### Tech Stack
+
+| Layer | Technology | Version |
+|---|---|---|
+| Runtime | Node.js | 18.19.0 |
+| API Framework | Express.js | 4.18.2 |
+| Frontend | React | 18.2.0 |
+| Build Tool | Vite | 5.1.4 |
+| Database | PostgreSQL | 15.4 |
+| ORM | Prisma | 5.10.2 |
+| Monorepo | Turborepo | 1.12.4 |
+| Testing | Jest + React Testing Library | 29.7 / 14.2 |
+| Language | TypeScript | 5.3.3 |
+
+### Entry Points
+
+| Entry Point | File | Purpose |
+|---|---|---|
+| API Server | `packages/api/src/server.ts` | Express app bootstrap |
+| Web App | `packages/web/src/main.tsx` | React SPA entry |
+| DB Migrations | `packages/api/prisma/migrations/` | Schema migrations (47 files) |
+| Seed Script | `scripts/seed.ts` | Development data seeding |
+| CI Pipeline | `.github/workflows/ci.yml` | Build + test + deploy |
+
+---
+
+## 2. Dependency Graph Summary
+
+### Internal Dependencies
+
+```
+web → shared (types, validation)
+api → shared (types, validation)
+web → api (via HTTP — no direct import)
+```
+
+No circular dependencies between packages.
+
+### Circular Dependencies Within API Package
+
+3 circular dependencies detected via `madge --circular packages/api/src/`:
+
+| Cycle | Files | Severity |
+|---|---|---|
+| 1 | `services/taskService.ts` ↔ `services/notificationService.ts` | High — causes import order bugs |
+| 2 | `repositories/projectRepo.ts` ↔ `repositories/taskRepo.ts` | Medium — shared query logic |
+| 3 | `utils/permissions.ts` ↔ `services/authService.ts` | Low — only type imports |
+
+**Recommendation**: Extract shared logic into dedicated modules. Cycle 1 should use an event emitter pattern instead of direct service-to-service calls.
+
+### External Dependencies
+
+**Outdated packages** (12 major versions behind):
+
+| Package | Current | Latest | Risk |
+|---|---|---|---|
+| express | 4.18.2 | 5.0.1 | Medium — major API changes |
+| react-router-dom | 6.22.0 | 7.1.0 | Medium — loader API changes |
+| @types/node | 18.19.0 | 22.1.0 | Low — type definitions only |
+| helmet | 6.2.0 | 8.0.0 | Low — minor config changes |
+| zod | 3.22.4 | 4.0.0 | High — schema API changes |
+| eslint | 8.57.0 | 9.12.0 | Medium — config format change |
+| prisma | 5.10.2 | 6.2.0 | High — query engine changes |
+| axios | 0.27.2 | 1.7.9 | Medium — interceptor API changes |
+| winston | 3.11.0 | 4.0.0 | Low — transport config changes |
+| multer | 1.4.5 | 2.0.0 | Low — middleware signature change |
+| jsonwebtoken | 9.0.0 | 10.0.0 | Medium — algorithm defaults change |
+| dotenv | 16.4.1 | 17.0.0 | Low — minimal breaking changes |
+
+**Vulnerabilities** (2 high severity):
+
+| Package | Vulnerability | Severity | Fix |
+|---|---|---|---|
+| axios@0.27.2 | SSRF via proxy config (CVE-2023-45857) | High | Upgrade to 1.6.0+ |
+| jsonwebtoken@9.0.0 | Algorithm confusion (CVE-2024-33663) | High | Upgrade to 10.0.0+ |
+
+**Abandoned packages** (0 detected): All dependencies are actively maintained.
+
+**License issues** (0 detected): All dependencies use MIT or Apache-2.0 licenses.
+
+---
+
+## 3. Hotspot Analysis
+
+### Top 10 Most Changed Files (Last 6 Months)
+
+| Rank | File | Changes | Complexity | Bug Fixes | Risk |
+|---|---|---|---|---|---|
+| 1 | `api/src/services/taskService.ts` | 47 | High (CC: 23) | 8 | **Critical** |
+| 2 | `web/src/features/tasks/TaskBoard.tsx` | 38 | High (CC: 18) | 5 | **Critical** |
+| 3 | `api/src/controllers/taskController.ts` | 31 | Medium (CC: 12) | 3 | High |
+| 4 | `shared/src/validation/taskSchema.ts` | 28 | Low (CC: 4) | 2 | Medium |
+| 5 | `web/src/features/tasks/TaskFilters.tsx` | 25 | Medium (CC: 11) | 4 | High |
+| 6 | `api/src/services/notificationService.ts` | 22 | Medium (CC: 14) | 3 | High |
+| 7 | `api/src/repositories/taskRepo.ts` | 20 | Medium (CC: 10) | 2 | Medium |
+| 8 | `web/src/shared/ui/DataTable.tsx` | 19 | High (CC: 16) | 6 | **Critical** |
+| 9 | `api/src/middleware/auth.ts` | 17 | Low (CC: 6) | 1 | Low |
+| 10 | `web/src/features/auth/LoginForm.tsx` | 15 | Low (CC: 5) | 1 | Low |
+
+### Correlation with Bug Reports
+
+Files #1, #2, and #8 appear in 60% of all bug-fix commits. The task service alone accounts for 8 of 31 total bug fixes in the past 6 months.
+
+### Files Changed Together (Coupling)
+
+| File Pair | Co-change Count | Expected? |
+|---|---|---|
+| `taskService.ts` + `taskController.ts` | 24 | Yes — same feature |
+| `taskService.ts` + `notificationService.ts` | 18 | No — should be decoupled |
+| `TaskBoard.tsx` + `TaskFilters.tsx` | 15 | Yes — same UI feature |
+| `taskSchema.ts` + `taskService.ts` | 14 | Yes — validation + logic |
+| `DataTable.tsx` + `TaskBoard.tsx` | 12 | No — generic component coupled to feature |
+
+**Recommendation**: `notificationService` should subscribe to task events rather than being called directly. `DataTable` needs a cleaner props interface to reduce coupling to specific features.
+
+---
+
+## 4. Tech Debt Inventory
+
+### Summary by Category
+
+| Category | Items | Critical | High | Medium | Low |
+|---|---|---|---|---|---|
+| Code | 4 | 1 | 1 | 1 | 1 |
+| Design | 3 | 0 | 2 | 1 | 0 |
+| Infrastructure | 2 | 1 | 1 | 0 | 0 |
+| Testing | 4 | 1 | 2 | 1 | 0 |
+| Documentation | 2 | 0 | 0 | 1 | 1 |
+| **Total** | **15** | **3** | **6** | **4** | **2** |
+
+### Full Inventory
+
+| ID | Category | Description | Impact | Effort | Priority | Status |
+|---|---|---|---|---|---|---|
+| TD-001 | Code | `taskService.ts` has CC of 23, 480 lines — needs splitting | 5 | 3 | 15 | New |
+| TD-002 | Code | Duplicated validation logic in 3 controllers (task, project, user) | 3 | 2 | 12 | New |
+| TD-003 | Code | 43 TODO/FIXME markers across the codebase | 2 | 2 | 8 | Backlog |
+| TD-004 | Code | `DataTable.tsx` has 16 props — abstraction too leaky | 3 | 3 | 9 | New |
+| TD-005 | Design | Task ↔ Notification circular dependency | 4 | 3 | 12 | New |
+| TD-006 | Design | Auth logic spread across middleware, service, and utils | 4 | 4 | 8 | New |
+| TD-007 | Design | API error responses inconsistent — 3 different formats in use | 3 | 2 | 12 | New |
+| TD-008 | Infra | 2 high-severity vulnerabilities in dependencies | 5 | 2 | 20 | **Urgent** |
+| TD-009 | Infra | Node.js 18 approaching EOL (April 2025) — need upgrade to 22 | 4 | 3 | 12 | Planned |
+| TD-010 | Testing | No E2E tests — critical user flows untested end-to-end | 5 | 4 | 10 | New |
+| TD-011 | Testing | Service layer coverage at 45% — business logic at risk | 4 | 3 | 12 | New |
+| TD-012 | Testing | 7 flaky tests in CI — `TaskBoard` integration tests | 4 | 2 | 16 | New |
+| TD-013 | Testing | No contract tests between web and API | 3 | 3 | 9 | Backlog |
+| TD-014 | Docs | API documentation 4 months stale — missing 8 endpoints | 3 | 2 | 12 | Backlog |
+| TD-015 | Docs | No Architecture Decision Records (ADRs) | 2 | 1 | 10 | Backlog |
+
+---
+
+## 5. Test Coverage Analysis
+
+### Coverage by Package
+
+| Package | Statements | Branches | Functions | Lines |
+|---|---|---|---|---|
+| api/controllers | 85% | 72% | 88% | 85% |
+| api/services | 45% | 38% | 50% | 45% |
+| api/repositories | 62% | 55% | 65% | 62% |
+| api/middleware | 90% | 85% | 92% | 90% |
+| web/features | 58% | 42% | 55% | 58% |
+| web/shared/ui | 72% | 60% | 75% | 72% |
+| shared/validation | 95% | 90% | 98% | 95% |
+| **Overall** | **65%** | **55%** | **68%** | **65%** |
+
+### Critical Coverage Gaps
+
+| Module | Coverage | Risk Level | Concern |
+|---|---|---|---|
+| `api/services/taskService.ts` | 38% | **Critical** | Core business logic, most bug-prone file |
+| `api/services/notificationService.ts` | 42% | High | User-facing notifications, failure = silent bugs |
+| `api/services/paymentService.ts` | 35% | **Critical** | Financial transactions, error = revenue loss |
+| `web/features/tasks/TaskBoard.tsx` | 30% | High | Primary user interface, 5 bug fixes in 6 months |
+
+### E2E Test Status
+
+**No E2E tests exist.** Critical untested flows:
+- User registration → email verification → login
+- Create project → add members → create tasks → assign
+- Task status transitions → notification triggers
+- File upload → attachment to task → download
+
+---
+
+## 6. Recommendations
+
+Prioritized list of improvements, ordered by impact and effort:
+
+### Immediate (This Sprint)
+
+| # | Action | Effort | Resolves |
+|---|---|---|---|
+| 1 | Upgrade axios to 1.7.x and jsonwebtoken to 10.x | 2 hours | TD-008 (vulnerabilities) |
+| 2 | Fix 7 flaky tests in TaskBoard integration | 4 hours | TD-012 |
+| 3 | Standardize API error response format | 1 day | TD-007 |
+
+### Next 2-3 Sprints
+
+| # | Action | Effort | Resolves |
+|---|---|---|---|
+| 4 | Split `taskService.ts` into domain-specific services | 3 days | TD-001, partially TD-005 |
+| 5 | Add tests for service layer (target: 80% coverage) | 3 days | TD-011 |
+| 6 | Break circular dependency with event emitter pattern | 2 days | TD-005 |
+| 7 | Upgrade Node.js from 18 to 22 | 2 days | TD-009 |
+
+### Next Quarter
+
+| # | Action | Effort | Resolves |
+|---|---|---|---|
+| 8 | Implement E2E test suite for 5 critical user flows | 2 weeks | TD-010 |
+
+### Estimated Impact
+
+If all recommendations are implemented:
+- **Bug rate reduction**: ~40% (based on hotspot coverage improvement)
+- **Developer velocity**: +20% (less debugging, clearer architecture)
+- **Security posture**: 2 critical vulnerabilities eliminated
+- **Test confidence**: coverage from 65% to ~82% overall
+- **Onboarding time**: reduced from ~3 weeks to ~1 week (with ADRs and updated docs)
+
+---
+
+*Report generated using codebase-analysis skill. Metrics collected via madge, eslint, jest --coverage, git log analysis, and npm audit.*