santimattius/performance-compose-skills/compose-audit

Performance First

Every Compose frame runs three phases. Cost rises left-to-right; restart scope shrinks left-to-right.

Audits prioritize issues that force Composition restarts or break lifecycle/correctness. Layout and Drawing phase issues are classified as warning unless they cause measurable jank with evidence.

Performance Toolchain

WARNING: NEVER profile in debug builds. Debug disables R8, inlining, and Strong Skipping — numbers are meaningless. Always profile a release build with profileable enabled or a benchmark build type.

When to Use

Use this skill when:

• Auditing an existing Compose or Compose Multiplatform codebase for performance and correctness
• The user asks for a "Compose review", "recomposition audit", or "CMP audit"
• You need a severity-ranked report that points to the right fix skill
• Onboarding to an unfamiliar Compose project and need a structured first pass

When NOT to Use

Do not load this skill when the user already named a narrow topic — load the specific skill instead:

This skill diagnoses and routes. It does not replace downstream remediation guidance.

Audit Workflow

Execute phases in order. Do not skip discovery.

Phase 1 Discovery → Phase 2 Static Scan → Phase 3 Severity → Phase 4 Routing → Phase 5 Report

Phase 1 — Discovery

See references/discovery-playbook.md.

Outputs for the report header: project_type, compose_version, compiler_reports_available, source_sets, entry_points, sampling.

STOP: If no Compose dependency and no @Composable in project sources → emit No Compose codebase detected and exit.

Phase 2 — Static Scan

Load references/detection-catalog.md and assets/routing-table.md.

For each pattern_id, run the ripgrep recipe (or Grep tool with the same pattern). Record:

raw_signal:
  pattern_id: EFF-LAUNCHED-EFFECT-UNIT
  file: ...
  line: ...
  snippet: ...
  source_set: androidMain | main | commonMain | ...

Rule: Read 5–15 lines of context. If the match is a false positive, discard — do not list in the report.

Phase 3 — Severity Classification

Apply references/severity-rubric.md. Start from Default Severity in the routing table. You may upgrade with evidence; never downgrade.

Phase 4 — Routing

Look up pattern_id in assets/routing-table.md. Apply Disambiguator when present:

If no row matches, add to Notes only — never as a Finding.

Phase 5 — Report Generation

Copy assets/AUDIT-REPORT.md, fill placeholders, enforce caps:

Default: render inline in chat. On request, write audit/AUDIT-REPORT-<timestamp>.md at project root.

Order Next Skills to Load by severity weight (critical=3, warning=2, suggestion=1) per skill.

Detection Catalog (summary)

Full heuristics: references/detection-catalog.md. Routing: assets/routing-table.md.

Severity Rubric

Details: references/severity-rubric.md.

Skill Routing

Invariants:

1. Every finding has exactly one pattern_id and one canonical skill.
2. Fix sketches are 1–3 lines — point to a section in the downstream SKILL.md, do not paste full fixes.
3. Unrouteable signals → Notes, not Findings.

Canonical skills (from AGENTS.md):

• compose-composition-core
• compose-modifier-system
• compose-effects
• compose-animations
• compose-architecture
• compose-navigation-nav3
• compose-previews-tooling
• compose-quality

Compose vs Compose Multiplatform

Detail: references/cmp-considerations.md. Official CMP docs: https://kotlinlang.org/docs/multiplatform/compose-multiplatform.html

Tooling Integration

ripgrep / Grep

Prefer rg (respects .gitignore). Scope with --glob '**/src/commonMain/**' for CMP patterns.

rg -n 'LaunchedEffect\s*\(\s*Unit\s*\)' -t kotlin

Compose Compiler Reports

If reportsDestination exists, read *-classes.txt and *-composables.txt for unstable/skippable validation.

android-cli — docs search

For Jetpack Compose API recommendations:

android docs search 'collectAsStateWithLifecycle'

Store top result URL in evidence_docs. If CLI unavailable: evidence_docs: (android-cli unavailable).

context7 MCP (CMP)

For CMP-* findings, resolve docs via context7 (/jetbrains/compose-multiplatform, /kotlinlang/docs).

Report Contract

Every audit MUST include:

• Discovery metadata (project type, version, sampling)
• Summary counts per severity (with cap flags)
• Findings with: pattern_id, file:line, evidence snippet, rationale, recommended skill link, fix sketch, docs consulted
• Overflow table when caps exceeded
• Next Skills to Load ordered list

Template: assets/AUDIT-REPORT.md.

Pitfalls (when running the audit)

Deviations from other skills in this repo

• `assets/` folder — templates (AUDIT-REPORT.md, routing-table.md) are agent-fillable; references/ is read-only background.
• No Kotlin remediation samples in this file — remediation lives in the nine routed skills.
• Pairs with all nine skills — there is no single "vs" neighbor section; use Skill Routing + routing table.

References