Single-Session Engineering Productivity Audit

Purpose

Evaluates developer experience (DX), debugging capabilities, and offline support infrastructure. Identifies friction points in development workflows and provides actionable recommendations for improvement.

Execution Mode Selection

| Condition | Mode | Time | | ----------------------------------------- | ---------- | ------- | | Task tool available + no context pressure | Parallel | ~15 min | | Task tool unavailable | Sequential | ~45 min | | Context running low (<20% remaining) | Sequential | ~45 min | | User requests sequential | Sequential | ~45 min |

Section A: Parallel Architecture (3 Agents)

When to use: Task tool available, sufficient context budget

Agent 1: dx-golden-path-auditor

Focus Areas:

Developer onboarding friction
npm scripts completeness
Setup automation (doctor scripts, env validation)
Development workflow ergonomics

Files:

package.json (scripts section)
scripts/ directory
.env.example, .env.local
README.md, DEVELOPMENT.md

Checks:

# Count npm scripts
grep -c '"[^"]*":' package.json

# Check for setup/doctor scripts
ls scripts/*.js 2>/dev/null | grep -E 'setup|doctor|verify'

# Check for dev:offline script
grep -c "dev:offline" package.json

Agent 2: debugging-ergonomics-auditor

Focus Areas:

Structured logging vs console.log ratio
Correlation ID support for request tracing
Error message quality and user guidance
Sentry integration completeness

Files:

lib/logger.ts
*.ts *.tsx files (console.log patterns)
functions/src/**/*.ts (Cloud Functions logging)
app/**/error.tsx (error boundaries)

Checks:

# Console.log to logger ratio
echo "Console.log calls:"
grep -r "console.log" --include="*.ts" --include="*.tsx" app/ lib/ components/ | wc -l
echo "Logger calls:"
grep -r "logger\." --include="*.ts" --include="*.tsx" app/ lib/ components/ | wc -l

# Correlation ID patterns
grep -r "correlationId\|correlation-id\|x-request-id" --include="*.ts" .

Agent 3: offline-support-auditor

Focus Areas:

Firebase IndexedDB persistence configuration
Service worker presence and functionality
Offline write queue implementation
Network status indicators and user feedback

Files:

lib/firebase.ts
public/sw.js (if exists)
components/status/offline-indicator.tsx
lib/offline-queue.ts (if exists)

Checks:

# Firebase persistence
grep -r "enableIndexedDbPersistence\|enablePersistence" lib/ app/

# Service worker
ls -la public/sw.js 2>/dev/null || echo "No service worker"

# LocalStorage vs IndexedDB usage
grep -r "localStorage" --include="*.ts" --include="*.tsx" | wc -l
grep -r "indexedDB\|IDB\|Dexie" --include="*.ts" --include="*.tsx" | wc -l

Parallel Execution Command

Invoke all 3 agents in a SINGLE Task message:

Task 1: dx-golden-path-auditor agent - audit setup, scripts, onboarding Task 2:
debugging-ergonomics-auditor agent - audit logging, error handling Task 3:
offline-support-auditor agent - audit persistence, service workers

Section B: Sequential Fallback

When to use: Task tool unavailable, context pressure, or user request

Step 1: Golden Path & DX (10 min)

Review package.json scripts section
Check for setup/doctor automation scripts
Verify .env.example completeness
Assess README setup instructions
Identify missing "golden path" scripts

Step 2: Debugging Ergonomics (10 min)

Calculate console.log vs logger ratio
Search for correlation ID patterns
Review error boundary implementations
Check Sentry integration in logger
Assess error message quality

Step 3: Offline Support (10 min)

Check Firebase persistence configuration
Look for service worker implementation
Review offline indicator component
Search for write queue patterns
Assess localStorage vs IndexedDB usage

Output Requirements

Report File

Create docs/audits/comprehensive/audit-engineering-productivity-report.md:

# Engineering Productivity Audit - {DATE}

## Baselines

| Metric                   | Value |
| ------------------------ | ----- |
| npm scripts count        | X     |
| Console.log calls        | X     |
| Logger calls             | X     |
| Structured logging ratio | X:Y   |
| LocalStorage usages      | X     |
| IndexedDB usage          | X     |
| Service worker           | Y/N   |
| Firebase persistence     | Y/N   |

## Findings Summary

| Severity | Count | Category       |
| -------- | ----- | -------------- |
| S0       | X     | -              |
| S1       | X     | Category names |
| S2       | X     | Category names |
| S3       | X     | Category names |

## Detailed Findings

### 1. Golden Path & DX

[Findings here]

### 2. Debugging Ergonomics

[Findings here]

### 3. Offline Support

[Findings here]

## Quick Wins (E0-E1)

[Prioritized list of low-effort fixes]

## Recommendations

### Immediate (E0-E1)

[List]

### Short-term (E2)

[List]

### Long-term (E3)

[List]

JSONL File

Create docs/audits/comprehensive/audit-engineering-productivity-findings.jsonl:

CRITICAL - Use this exact schema:

{
  "category": "engineering-productivity",
  "title": "Short specific title",
  "fingerprint": "engineering-productivity::primary_file::identifier",
  "severity": "S0|S1|S2|S3",
  "effort": "E0|E1|E2|E3",
  "confidence": 75,
  "files": ["array/of/file/paths.ts"],
  "why_it_matters": "1-3 sentences explaining impact",
  "suggested_fix": "Concrete remediation direction",
  "acceptance_tests": ["Array of verification steps"]
}

Category Definitions

| Category | Description | | ---------- | ------------------------------------------ | | GoldenPath | Setup, scripts, onboarding, dev workflow | | Debugging | Logging, tracing, error handling, messages | | Offline | Persistence, service workers, queues, sync |

Severity Scale

| Level | Name | Definition | | ----- | -------- | ---------------------------------------- | | S0 | Critical | Data loss risk, production breaking | | S1 | High | Significant dev friction, missing core | | S2 | Medium | Maintainability drag, inconsistency | | S3 | Low | Polish, minor improvements, nice-to-have |

Effort Scale

| Level | Name | Definition | | ----- | ------- | --------------------------- | | E0 | Minutes | Quick fix, trivial change | | E1 | Hours | Single-session work | | E2 | Days | 1-3 days or staged PR | | E3 | Weeks | Multi-PR, multi-week effort |

Prior Audit Reference

Check docs/audits/single-session/engineering-productivity/ for prior findings and track carryover issues.

TDMS Integration

After audit completion, findings should be ingested into MASTER_DEBT.jsonl:

node scripts/debt/intake-audit.js \
  docs/audits/comprehensive/audit-engineering-productivity-findings.jsonl \
  --source "audit-engineering-productivity-$(date +%Y-%m-%d)"

Related Skills

/audit-comprehensive - Run all 7 domain audits
/audit-process - CI/CD and automation audit (overlaps with DX)
/audit-code - Code quality audit

Version History

| Version | Date | Description | | ------- | ---------- | ---------------------- | | 1.0 | 2026-02-03 | Initial skill creation |