Imported from antoinefink/interleave (.agents/skills/deep-review/SKILL.md). Install upstream with npx skills add antoinefink/interleave --skill deep-review. Copyright stays with the author.

Deep review / harden the whole app (per-component audit → fix → commit)

This skill encapsulates the cross-cutting quality pass: decompose the app into many components, and for each run an adversarial audit → fix → re-audit loop, fixing everything fixable and committing per component. It catches emergent defects a per-task build gate can't see (cross-component state bleed, design inconsistency across screens, data-integrity gaps, missing tests) because it audits each part in situ, in the whole system.

Run it with the Workflow tool. It is long and thorough by design — that's the point.

What "good" means for each component

The auditor verifies, and the fixer ensures:

• Implemented as expected — every feature matches its roadmap line + docs/tasks/ spec; nothing is stubbed, faked, or half-wired (real data flows through window.appApi).
• Design works — UI matches the design kit (design/, design/kit/): tokens (no hard-coded hex/px), correct in light AND dark, lucide icons, dense-but-calm, the load-bearing patterns (FSRS-vs-attention SchedulerChip, actionable lineage).
• Nothing broken, weird, or nonsensical — no bugs, dead buttons, empty/incoherent states, race conditions, mislabeled data, or behavior that contradicts the product intent.
• Enough tests — the component's behaviors and edge cases are actually covered; weak/missing tests are a finding, and the fixer adds them.
• Architecture invariants hold (see AGENTS.md): renderer never touches SQLite/Node/fs (only window.appApi); mutations transactional + operation_log; domain logic out of React; source lineage sacred; FSRS for cards only vs the attention scheduler for sources/extracts.

The per-component loop (NEVER halts)

For each component: audit → (if findings) fix → re-audit → …, up to 6 rounds, then commit any changes and move on. Unlike the build skill, this pass does not halt — a stubborn component is committed + flagged, and the run continues to the rest. At the end, report every component that used all 6 rounds (with its residual findings) and all deferred massive-refactor items.

The bar (same strict rule as the build skill): fix EVERYTHING the auditor finds — large and small (small wins, small mistakes, polish, weak tests) — and only defer a fix that genuinely requires a massive refactor (flag it; don't force it). passed=true only when no fixable issue remains for that component.

Decompose into many components (adapt to the current app)

Use ~15–20 phases — the backend layers as units, then each feature surface end to end, then cross-cutting passes. A proven decomposition (adapt to what exists now):

1. Domain core (packages/core) · 2. DB schema + migrations (packages/db) · 3. Repositories & services (packages/local-db) · 4. Schedulers (packages/scheduler) · 5. Editor (packages/editor) · 6. Electron main + security + the typed IPC/appApi boundary (apps/desktop) · 7. App shell, navigation, keyboard & command palette · 8. Capture & inbox · 9. Reader & document editing · 10. Extraction, lineage & hierarchy · 11. Priority, scheduling & queue · 12. Cards & card-quality · 13. FSRS review · 14. Concepts, tags, search & references · 15. Trash/undo, analytics & backup · 16. Design-system fidelity (cross-cutting UI/UX) · 17. End-to-end integration, data integrity & packaging.

Verification & guardrails

• Native pnpm: each audit re-runs pnpm typecheck && pnpm lint && pnpm test (fast — seconds), plus targeted pnpm e2e (Playwright→Electron) for UI components; the integration phase runs the full e2e + the packaging build.
• Stabilize the suite first. A pre-existing/flaky red test poisons the "checks green" gate and forces every component to the 6-round cap. Confirm green before starting (or fix the flake in an early phase).
• Bound heavyweight verifications so schema-constrained auditors don't exhaust their turn and fail to emit StructuredOutput (scope packaging/full-e2e to inspect-and-fast-checks where needed).
• Per-component commits make the long run resumable on a crash (Workflow({scriptPath, resumeFromRunId}); unchanged earlier agents cache-hit).
• Commit per component: subject harden(<area>): <summary>, body, trailer Co-Authored-By: Codex Opus 4.8 (1M context) <noreply@anthropic.com>. A component that audits clean makes no commit.

Workflow template (adapt the component list, then launch)

export const meta = {
  name: 'interleave-deep-review',
  description: 'Per-component deep review/harden: independent auditor (implemented-as-expected, design, no breakage, enough tests, invariants) → fixer loop ≤6 rounds → commit per component. Never halts; flags any component that uses all 6 rounds + deferred massive-refactor items.',
  phases: [ /* one { title } per component */ ],
}

const REPO = '/Users/antoine/Code/interleave'
const MAX_ROUNDS = 6
const BASE = 'pnpm typecheck && pnpm lint && pnpm test'

const AUDIT = {
  type: 'object', additionalProperties: false,
  required: ['passed', 'summary', 'findings'],
  properties: {
    passed: { type: 'boolean', description: 'true ONLY if this component is implemented as expected, the design works (light+dark, matches the kit), nothing is broken/weird/nonsensical, tests are sufficient, the invariants hold, the verification you ran is green, and NO fixable finding remains — large OR small. Only severity deferred-massive-refactor may remain.' },
    summary: { type: 'string', description: 'what you audited + which checks you re-ran + their result' },
    findings: { type: 'array', items: { type: 'object', additionalProperties: false,
      required: ['severity', 'category', 'title', 'detail', 'where'],
      properties: {
        severity: { type: 'string', enum: ['critical', 'major', 'minor', 'deferred-massive-refactor'] },
        category: { type: 'string', enum: ['bug', 'missing-feature', 'tests', 'ui', 'design', 'roadmap', 'architecture', 'quality'] },
        title: { type: 'string' }, detail: { type: 'string' }, where: { type: 'string' },
      } } },
  },
}
const COMMIT = { type: 'object', additionalProperties: false,
  required: ['committed', 'changed', 'commit_hash', 'message'],
  properties: { committed: { type: 'boolean' }, changed: { type: 'boolean' }, commit_hash: { type: 'string' }, message: { type: 'string' } } }

const ARCH = [
  'ARCHITECTURE INVARIANTS (Electron + native SQLite): renderer never touches SQLite/Node/fs (only the typed, Zod-validated window.appApi); mutations transactional + operation_log; domain logic in packages/*, not React; source lineage sacred; FSRS for cards only vs the attention scheduler for sources/extracts; verify with native pnpm; every feature survives an app restart.',
].join('\n')

// COMPONENTS: { key, title, ui, paths, refs, scope, verify }  — `refs` = roadmap milestone(s) +
// docs/tasks spec + (ui) the design-kit screens. `verify` = BASE (+ targeted e2e for ui; full e2e
// + packaging for the integration phase).
const COMPONENTS = [ /* ~15–20 entries; see the decomposition above */ ]

function auditPrompt(c, round, fixReport) { return [
  'You are an INDEPENDENT, STRICT QUALITY AUDITOR for the Interleave component: ' + c.title + '. cwd: ' + REPO + '. This is a hardening pass on already-built code — find REAL defects + gaps, not speculative rewrites.',
  'Scope: ' + c.scope + '\nCode: ' + c.paths + '\nRequirements (source of truth for "expected"): ' + c.refs + '. Also read AGENTS.md.',
  ARCH,
  (round > 1 ? 'A fixer just addressed the prior round (report below). Re-audit from scratch.\n<<<\n' + (fixReport || '') + '\n>>>' : ''),
  '1) Read the code + its requirements. 2) RE-RUN: ' + c.verify + ' (a red check is critical). 3) Audit: implemented-as-expected vs spec/roadmap; ' + (c.ui ? 'design works (matches the kit, light AND dark, lucide, the SchedulerChip + lineage patterns); ' : '') + 'nothing broken/weird/nonsensical; tests sufficient (cover behaviors + edge cases — gaps are findings); the invariants hold.',
  'STRICT: flag EVERY fixable issue — large AND small. Only severity=deferred-massive-refactor for fixes needing a massive refactor (does not block). Do NOT manufacture findings for taste; clean code passes round 1. passed=true ONLY if no fixable finding remains and the checks are green.',
].join('\n\n') }

function fixerPrompt(c, v) { return [
  'You are the FIXER for the Interleave component: ' + c.title + '. cwd: ' + REPO + '. ' + ARCH,
  'Auditor summary: ' + v.summary,
  'Fix EVERY finding that is not deferred-massive-refactor (small ones included; ADD missing tests; match the design kit for UI). Do NOT regress other parts — the fast suite must stay green.',
  'Findings:\n' + JSON.stringify(v.findings, null, 2),
  'Re-run GREEN: ' + c.verify + '. Do NOT commit. Report changes per finding + fresh output.',
].join('\n\n') }

function commitPrompt(c, clean, rounds) { return [
  'You are the COMMITTER for the hardening component: ' + c.title + ' (' + c.key + '). cwd: ' + REPO + '. Default branch. Loop ran ' + rounds + ' round(s), ended ' + (clean ? 'CLEAN' : 'at the 6-round cap') + '.',
  '1. git status. If clean (no changes) → committed=false, changed=false, message="no changes — audited clean".',
  '2. If changed: run ' + BASE + '. If red, do NOT commit (committed=false, changed=true, explain). If green: git add -A && ONE commit, subject "harden(' + c.key + '): <summary>", body, trailer EXACTLY: Co-Authored-By: Codex Opus 4.8 (1M context) <noreply@anthropic.com>. Do NOT push.',
  'Return committed, changed, commit_hash (short/empty), message.',
].join('\n') }

const results = []
for (const c of COMPONENTS) {
  phase(c.title)
  let round = 0, clean = false, verdict = null, fixReport = ''
  while (round < MAX_ROUNDS) {
    round++
    verdict = await agent(auditPrompt(c, round, fixReport), { phase: c.title, label: 'audit:' + c.key + '#' + round, agentType: 'general-purpose', schema: AUDIT })
    if (!verdict) break
    const blocking = (verdict.findings || []).filter(f => f.severity !== 'deferred-massive-refactor')
    if (verdict.passed && blocking.length === 0) { clean = true; break }
    fixReport = await agent(fixerPrompt(c, verdict), { phase: c.title, label: 'fix:' + c.key + '#' + round, agentType: 'general-purpose' })
  }
  const commit = await agent(commitPrompt(c, clean, round), { phase: c.title, label: 'commit:' + c.key, agentType: 'general-purpose', schema: COMMIT })
  results.push({ component: c.key, rounds: round, clean, capped: !clean,
    committed: commit ? !!commit.committed : false, commit_hash: commit ? commit.commit_hash : '',
    residual: clean ? [] : (verdict?.findings || []).filter(f => f.severity !== 'deferred-massive-refactor'),
    deferred: (verdict?.findings || []).filter(f => f.severity === 'deferred-massive-refactor') })
  // NEVER halt — continue to the next component regardless.
}
const capped = results.filter(r => r.capped)
return { components: results, cappedComponents: capped, note: capped.length ? (capped.length + ' component(s) hit the 6-round cap — see cappedComponents.') : 'All components reached a clean audit within 6 rounds.' }

After it completes, independently verify green at HEAD (pnpm typecheck && lint && test, plus a full pnpm e2e), and report: per-component rounds + commit, the capped components with residual findings, and all deferred massive-refactor items. (Re-run a flaky full e2e fresh before treating a CI/e2e failure as real — one worker launches Electron per test, so it can flake under load.)