futo-notes

Rebuild tangled or AI-generated-looking code — one function up to an entire subsystem — from its observable behavioral contract while preserving external functionality and discarding accidental architecture. Optionally prunes the contract itself first (keep/simplify/drop triage of spec behaviors, human-gated) when the requester has said features may be dropped. Use when asked to identify the next "AI slop" area, deslop or radically simplify a codebase, rewrite a subsystem from scratch, start from tests, replace a giant orchestrator/controller/component, contract-rewrite something, "do this like the sync rewrite", preserve outside behavior without retaining internals, prune or triage a feature surface ("features I'd be OK dropping"), or turn legacy tests into a new implementation and MR. Not for bug fixes (/bugfix), small cleanups (/simplify), or changes that keep the existing structure.

Run the behavioral spec in docs/spec/ against the real apps — a parallel, story-driven QA sweep across desktop, iOS, and Android plus cross-client sync. Use when the user says "verify specs", "run the specs", "spec pass", "QA the specs", "check the app against the spec", or "/verify-specs [scope]". A bare run does the full spec (all surfaces × all platforms + sync mesh); "since the last tagged release" (or any scope phrase) narrows to the surfaces/platforms the diff touched. Fans out Sonnet low-effort app-qa legs, escalates FAILs to high effort, and is built to survive session-limit deaths without losing work.

Parallel QA of one or more merge requests across desktop/iOS/Android, including cross-client sync. Use when the user wants MRs tested — "test MR !123", "QA these five MRs in parallel", "spin up QA for my open MRs", "test this branch on mobile" — or wants a full spec pass. Creates a worktree per MR, pre-builds, fans out app-qa agents concurrently, and aggregates verdicts.

Diagnose and fix GitLab CI/pipeline failures, and harden .gitlab-ci.yml against this repo's recurring failure classes. Use when the user says "pipeline failed", "CI is red", "the tag build failed", "publish:android/publish:ios failed", "check the pipeline", "why didn't the release go out", "harden CI", or before tagging a release ("pre-tag check"). Also load this BEFORE editing .gitlab-ci.yml for any reason — it encodes the hard rules that past pipeline breakage taught.

Drive the factory/ judge harness that compares our CM6 live-preview editor against Obsidian scenario-by-scenario, triage divergences, and turn confirmed ones into fixes locked by markdown-spec cases. Use when the user says "run the factory", "compare to Obsidian", "editor parity", "review the visual report", "why does Obsidian render this differently", or after editor changes (liveMarkdownTransform, markdown.css, cursor movement) that should be checked against the oracle.

Keep docs/spec/ (the behavioral source of truth for all three apps) in lockstep with reality. Use when the user says "update the spec", "record a gap", "close that gap", "spec pass", "is the spec up to date", after landing any behavior change, when a spec-gaps-check closure probe fires, or when QA findings need to be turned into spec lines. Owns the full gap lifecycle - hidden-affordance verification, gap wording, GAPS.md regeneration, and closure probes.

Run the appropriate verification chain for recent changes. Detects what changed and runs build, tests, smoke checks, and visual UI verification. Use when the user says "verify", "check this", "does it work", "test it", "make sure X works", or after completing a feature/fix. Also use whenever the user wants to see a change running for real on ANY platform — the desktop Tauri app, the web dev server, the native iOS app on a simulator, the native Android app on an emulator/device, or Windows WebView2 in the qemu VM — including requests like "run it on the simulator", "screenshot the app on Android", or verifying a specific feature regardless of recent changes.

Reviews Swift code for concurrency correctness, modern API usage, and common async/await pitfalls. Use when reading, writing, or reviewing Swift concurrency code.

Writes, reviews, and improves Swift Testing code using modern APIs and best practices. Use when reading, writing, or reviewing projects that use Swift Testing.

Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state management and `@Observable` data flow, view composition and invalidation/performance, lists and `ForEach` identity, environment usage, localization, animations, Liquid Glass adoption, migrating soft-deprecated APIs, or Instruments `.trace` capture/analysis for hangs, hitches, CPU hotspots, or excessive view updates.

Multi-agent slow code review. Runs Claude's code-review, /codex:review, and /codex:adversarial-review against the current diff or a PR, dedupes findings, ranks them critical/high/medium/low, and walks through fixes high-severity first. Inspired by Nolan Lawson's "using AI to write better code more slowly" workflow. Use when the user says "slow review", "deep review", "review with codex", "multi-agent review", "triple review", or wants a thorough cross-checked review before merging — especially before shipping sync, auth, encryption, migration, or other high-stakes changes. Trades speed for catching real bugs and surfacing pre-existing issues. Not for tiny diffs.

Full release workflow: run tests, create MR, generate changelog with Zulip mentions, monitor pipeline, and post release announcement. Use when the user says "release", "ship it", "merge and release", or is ready to merge changes to main.

Adversarial testing agent. Takes natural language test targets ("test sync conflict resolution, semantic search, markdown tables"), generates adversarial scenarios, executes them, and reports structured verdicts comparing actual vs expected behavior. Use when the user says "test X", "can you test", "X needs testing", "break this", "QA this", or describes features/fixes that need adversarial validation. Unlike /verify (which runs existing test suites), /test-agent generates NEW ephemeral test scenarios designed to break things.

Fix bugs with a test-first approach that prevents regressions. Writes a failing regression test immediately, then diagnoses the root cause, applies the minimal fix, and verifies. Use this skill whenever the user reports a bug, pastes an error or stack trace, says "fix this", describes unexpected behavior, mentions something that "used to work", or asks you to debug an issue — even if they don't explicitly say "bug". Also use when the user wants to investigate flaky behavior or track down why something is broken.

Fetch messages from FUTO Zulip channels. Use when the user asks about Zulip messages, feedback, bug reports, or wants to check what's been discussed on Zulip.