@rubix0270/arboris 1.0.0

package/prisma/skills/competitive-platform-analysis/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: competitive-platform-analysis
+description: >-
+  Use when scoping a competitive landscape — identifying, categorising, and
+  score-filtering a competitor set before any benchmarking begins. Decides who
+  counts as a competitor, which tier they belong to, and which sources to mine.
+  First step in the three-skill competitive pipeline; precedes
+  benchmark-methodology.
+---
+
+# Competitive Platform Analysis
+
+Use this skill to decide **who to benchmark** and **where to find them** before
+any scoring begins. A competitive analysis is only as good as its frame: the
+wrong set makes the client look either unbeatable or doomed. The goal is a
+defensible, decision-relevant set — not an exhaustive census.
+
+## When to Activate
+
+- About to start a competitive benchmarking project and need to define the competitor set first.
+- Unsure which companies belong in Direct / Adjacent / Aspirational tiers.
+- Need a defensible, pruned scope for a market landscape report.
+- Has a positioning brief and wants to identify who contests that position.
+- First step before running benchmark-methodology.
+
+## Client positioning brief (establish first)
+
+Before scoping the set, establish the client's positioning brief. If you don't
+already have it, run a short brand-discovery interview to elicit it — do **not**
+invent one and do **not** scope the set blind. The brief supplies:
+
+- **Identity / aesthetic register** — what kind of studio or company this is and
+  how it presents itself.
+- **Offer** — what services or products it delivers.
+- **Target clients** — who it sells to.
+- **Differentiator** — the moat or positioning argument the client believes in.
+- **Scoping consequence** — the implication for how to weight competitors (e.g.,
+  prioritize by distinctiveness vs. capability overlap vs. price).
+- **Strategic tension** — the paired axes that define the client's white-space
+  (e.g., memorability × hireability).
+
+**Do not proceed without the positioning brief.** A competitor list scoped
+without the client's lens is noise, not intelligence. The scoping consequence in
+particular determines which competitors are *strong* rivals (those that contest
+the client's moat) vs. merely overlapping on service menu.
+
+## Selection criteria
+
+For each candidate, capture these axes — they decide both inclusion and tier:
+
+- **Size / model** — solo, micro-studio (2–8), boutique (sub-30), mid-size
+  agency. Match the client's own band; same-band studios are the realistic
+  head-to-head set.
+- **Niche / specialization** — how closely the candidate's focus overlaps with
+  the client's offer. Tighter overlap = more direct.
+- **Geography / market** — EU vs US vs global-remote; language; time-zone reach.
+  Note whether they win the same clients the client targets.
+- **Pricing & engagement model** — productized sprints, retainer, project,
+  day-rate; transparent vs "contact us". Signals positioning maturity.
+- **Portfolio style** — generic vs. opinionated/editorial vs. contrarian. Closer
+  to the client's aesthetic register = more they contest the client's
+  distinctiveness.
+- **Technical depth / craft maturity** — relevant if the client's credibility
+  story includes public process work, open tooling, or documented systems.
+- **Brand strength** — does the studio have an ownable verbal/visual identity, or
+  is it interchangeable? Weight this per the client's scoping consequence.
+
+## Player taxonomy — axes to populate across
+
+Don't sort competitors into niche-specific buckets; sort them along a few
+generic axes so the landscape isn't skewed toward one archetype. These axes
+apply to any creative-service market (design, motion, copywriting, branding,
+content, film, etc.). Aim for breadth across each axis first, then prune to the
+most instructive.
+
+1. **Positioning stance** — *brand-led / editorial* (competes on identity,
+   voice, POV) vs *capability-led* (competes on craft, throughput, outcomes).
+   Populate both poles; the client's closest mirror sits at its own end.
+2. **Specialization** — *specialist* (one tight discipline or vertical) vs
+   *generalist* (broad service menu). Tighter overlap with the client's focus =
+   more direct.
+3. **Size / model** — *solo / micro* vs *boutique* vs *mid-size* vs
+   *enterprise-scale*. Same-band players are the realistic head-to-head; larger
+   bands are the aspirational/commercial-maturity reference.
+4. **Engagement format** — *productized* (named sprints, audits, fixed packages)
+   vs *bespoke* (custom project / retainer). Signals positioning maturity.
+5. **Distinctiveness posture** — *conventional / safe* vs *contrarian /
+   manifesto-driven*. The opinionated end is key for distinctiveness
+   benchmarking in any niche.
+6. **Evidence / credibility model** — *outcome-led* (metrics, named clients,
+   case depth) vs *aesthetic-led* (portfolio, awards). Tells you how each player
+   earns trust.
+7. **Brand strength of the operator** — *interchangeable* vs *cult / ownable
+   identity* (including senior independents who prove the "memorable solo brand"
+   model).
+8. **Market / reach** — *local / regional* vs *global-remote*; note whether they
+   win the same clients the client targets.
+
+Plot each candidate on the relevant axes; a competitor is *direct* when it sits
+near the client on positioning, specialization, size, and market at once.
+
+## Competitive tiers (how the set resolves)
+
+Group the final set into three tiers — this structure carries through to the
+report:
+
+- **Direct** — same band, overlapping offer, same client targets. The realistic
+  head-to-head.
+- **Adjacent** — partial overlap (one capability, or a different client size)
+  that pressures at the edges.
+- **Aspirational** — players the client is not competing with today but whose
+  brand or commercial maturity sets the bar to aim at.
+- *(Watch also for substitutes: no-code/AI tools, in-house teams, generalist
+  freelancers — note as a threat vector, not a profiled competitor unless
+  materially relevant.)*
+
+## Data sources (where to look)
+
+Match the source to the dimension you need. The platform *types* below are
+generic; substitute the ones native to the client's niche (e.g. Dribbble/Behance
+for design, showreel/Vimeo for motion, writing samples/published work for copy):
+
+- **Portfolio / craft platforms** — craft quality, range, aesthetic register
+  (e.g. Dribbble, Behance, Vimeo, or the niche's equivalent showcase).
+- **Awards / curated showcases** — craft ambition and editorial recognition;
+  over-indexes on flashy, so cross-check commercial credibility (e.g. Awwwards,
+  industry award lists).
+- **Competitor's own site** — primary source for positioning, voice, offer
+  packaging, pricing posture, named clients, manifesto/POV.
+- **LinkedIn** — team size/model, founder narrative, post cadence, client logos,
+  geography.
+- **Review directories** — reviews, named clients, project sizes, engagement
+  models; strongest signal for commercial credibility and enterprise-readiness
+  (e.g. Clutch.co or the niche's equivalent).
+- **Open / public work** — process repos, published samples, open creative
+  output: depth and craft-transparency evidence.
+- **Conference talks / podcasts / newsletters** — thought-leadership depth and
+  POV ownership.
+
+Always **verify claims across at least two sources** before treating a competitor
+attribute as fact (self-reported site copy ≠ verified outcome). Carry an
+adversarial-verification discipline into every profile.
+
+## Scoring matrix template (selection stage)
+
+A lightweight pre-filter to decide who graduates into full benchmarking. Score
+1–5; keep candidates that score high on **either** distinctiveness **or**
+credibility — the client's strategic tension means both poles are instructive.
+
+| Candidate | Positioning stance | Specialization | Size band | Tier | Offer overlap (1–5) | Distinctiveness (1–5) | Commercial credibility (1–5) | Craft proximity (1–5) | Include? |
+|-----------|--------------------|----------------|-----------|------|---------------------|------------------------|------------------------------|------------------------|----------|
+
+Rules of thumb (apply per the client's scoping consequence in the positioning brief):
+
+- High distinctiveness **and** high credibility → must-profile (proves the
+  client's target tension is achievable).
+- High distinctiveness, low credibility → cautionary case (memorable but
+  un-hireable — a potential failure mode to learn from).
+- High credibility, low distinctiveness → "competent but forgettable" mass the
+  client defines itself against.
+- Low on both → drop unless needed for landscape breadth.
+
+## Output of this stage
+
+A scoped, tiered competitor set (typically 10–18 candidates → 8–12 profiled),
+each tagged with its axis positions, tier, and source links, ready to hand to
+`benchmark-methodology`.
+
+## Anti-Patterns
+
+- **Scoping without a positioning brief.** A competitor list built without the client's lens is noise. The brief determines what counts as a real rival.
+- **Listing every similar company.** The goal is a defensible 10–18 candidate set, not a census. Breadth without pruning makes benchmarking unmanageable.
+- **Blurring the Direct/Adjacent/Aspirational tiers.** These tiers serve different strategic purposes. Mixing them produces a flat list that can't drive decisions.
+- **Relying on a single source per competitor.** Self-reported site copy is marketing, not fact. Verify attributes across at least two sources.
+- **Jumping straight to scoring.** This skill scopes and tiers the set. Benchmark-methodology handles scoring. Don't conflate the two steps.
+
+## Examples
+
+**Scenario:** A boutique brand-identity studio (2-person, EU-remote, productized
+sprints, contrarian/manifesto-driven aesthetic) wants to scope its competitive
+set before benchmarking. The strategic tension from the positioning brief is
+*memorability × hireability*.
+
+**Step 1 — eight-axis population (sample candidates):**
+
+| Candidate | Positioning stance | Specialization | Size band | Engagement | Distinctiveness | Evidence model | Brand strength | Market |
+|---|---|---|---|---|---|---|---|---|
+| Studio A | brand-led / editorial | identity only | micro | productized | contrarian | aesthetic-led | cult | global-remote |
+| Studio B | capability-led | broad DS+motion | boutique | bespoke | conventional | outcome-led | interchangeable | US |
+| Agency C | capability-led | brand+digital | mid-size | retainer | conventional | outcome-led | interchangeable | EU |
+| Freelancer D | brand-led | brand voice only | solo | day-rate | editorial | aesthetic-led | ownable | global |
+| Studio E | brand-led | brand strategy | micro | productized | manifesto-driven | outcome-led | cult | EU-remote |
+
+**Step 2 — pre-filter scoring (client scoping consequence: weight distinctiveness
+because the client's moat is POV-first, not capability breadth):**
+
+| Candidate | Offer overlap (1–5) | Distinctiveness (1–5) | Commercial credibility (1–5) | Craft proximity (1–5) | Tier | Include? |
+|---|---|---|---|---|---|---|
+| Studio A | 5 | 5 | 3 | 5 | Direct | ✓ must-profile |
+| Studio B | 3 | 2 | 5 | 3 | Adjacent | ✓ credibility anchor |
+| Agency C | 2 | 1 | 5 | 2 | Aspirational | ✓ scale reference |
+| Freelancer D | 4 | 4 | 2 | 4 | Direct | ✓ cautionary case |
+| Studio E | 5 | 5 | 4 | 4 | Direct | ✓ must-profile |
+
+**Step 3 — output handed to `benchmark-methodology`:**
+Five candidates (3 Direct, 1 Adjacent, 1 Aspirational), each tagged with
+axis positions, tier, and source links. Studio A and Studio E are the
+sharpest head-to-head rivals; Freelancer D is the "memorable but
+un-hireable" cautionary case to learn from.
+
+## Related Skills
+
+- `brand-discovery` — use first to establish the positioning brief and strategic tension that scopes the competitor set.
+- `benchmark-methodology` — the next step; takes the tiered set and scores each competitor across nine dimensions.

package/prisma/skills/competitive-report-structure/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: competitive-report-structure
+description: >-
+  Use after benchmark-methodology has produced scored competitor profile cards.
+  Assembles findings into a decision-grade report: landscape map, competitor
+  profiles, benchmarking matrix, white-space analysis, strategic recommendations,
+  and team alignment trigger questions. Final step in the three-skill competitive
+  pipeline.
+---
+
+# Competitive Report Structure
+
+Use this skill to assemble scored competitor cards into a decision-grade report.
+The report must answer three questions for the client: **who do we compete with,
+how do we compete, and where is our defensible white-space?** Every section
+earns its place by moving toward those answers — cut anything that doesn't.
+
+## When to Activate
+
+- All competitor profile cards from benchmark-methodology are complete and ready to assemble.
+- Need to present competitive findings to a founder, leadership team, or board.
+- The report must drive decisions (who to compete with, how, where the moat is) — not just document the landscape.
+- Preparing a client deliverable that must be auditable and defensible.
+
+## Client positioning brief (establish first)
+
+Before assembling the report, establish the client's positioning brief. It
+supplies:
+
+- **Strategic tension** — the paired axes (e.g., memorability × hireability)
+  that define the client's target white-space. All maps and synthesis resolve
+  back to this tension.
+- **Brand balance** — the intended proportional mix of the client's strategic
+  emphases (e.g., 60% strategy/evidence, 25% distinctiveness, 15% craft).
+  Every recommendation must be checked against this balance; flag any that
+  would shift it.
+- **Differentiator** — the framing principle for the executive summary and
+  white-space section.
+- **Target quadrant** — where the client intends to sit in the tension map;
+  confirming whether that quadrant is genuinely open is the report's central
+  empirical question.
+
+## Framing principle
+
+The whole report is organized around the client's strategic tension and
+recommendations resolve back to the client's deliberate brand balance.
+Recommendations that would break that balance must be flagged against it
+explicitly — "this move shifts the balance from X/Y/Z toward A/B/C; confirm
+intent."
+
+## Report sections
+
+### 1. Executive summary
+3–5 takeaways, decision-first. State the most important findings in plain
+language: where the client is strong, where it's exposed, who occupies its
+target white-space, and the top 2–3 moves. Written so a founder/PM reads only
+this and knows what to do. No methodology here.
+
+### 2. Market landscape & category framing
+Define the category and map it. Use a **multi-axis map** — at minimum a 2×2
+(e.g., *brand-led <-> capability-led* × *boutique <-> enterprise-scale*), and
+ideally the **client's tension plot** from `benchmark-methodology` as the
+headline map. Place every profiled competitor and the client. The map should
+make the client's intended position visually obvious and show how crowded (or
+empty) it is.
+
+### 3. Competitor tiers
+Organize the set into **Direct / Adjacent / Aspirational** (from
+`competitive-platform-analysis`). One short paragraph per tier explaining who's
+in it and why it matters to the client. This sets reader expectations before
+the detail.
+
+### 4. Benchmarking matrix
+The full **competitors × dimensions** table — the quantitative spine. Rows =
+competitors (grouped by tier), columns = the nine benchmark dimensions (note:
+dimension 9 — strategic tension — has two poles (e.g., Memorability and
+Hireability for a brand-studio client; substitute the client's own paired axes);
+represent them as two separate sub-columns rather than averaging them). Include
+the client's own honest self-assessment as a row for contrast. Use a **heatmap**
+(color or symbol scale) so strength/weakness patterns are scannable. Do **not**
+add a blended total column — report dimensions separately (per the bias
+controls). Call out the columns where the client leads and where it trails.
+
+### 5. Deep dives
+3–5 most instructive competitors in narrative form (from their profile cards).
+Choose for instruction, not ranking: the best exemplar of the target tension
+(high on both poles), the cautionary "one pole only" case, the "competent but
+forgettable" archetype the client defines against, plus any direct threat. Each
+deep dive: what they do, what the client should learn, what the client should
+avoid.
+
+### 6. White-space & threats
+The strategic heart. Two parts:
+
+- **White-space:** the position the client can own that rivals don't — argued
+  from the maps and matrix, not asserted. Confirm whether the target quadrant
+  (from the positioning brief) is genuinely open.
+- **Threats:** who/what pressures the client — a rival closing the gap,
+  substitutes (no-code/AI tools, in-house teams, generalist freelancers), or
+  category shifts. Be honest about the client's own risks (e.g., a bold identity
+  reading as un-serious to risk-averse buyers).
+
+### 7. Strategic recommendations
+Concrete, prioritized moves: who the client competes with, how it differentiates,
+and where to invest (offer packaging, evidence/case studies, thought leadership,
+brand sharpening). **Tie every recommendation back to the brand balance from the
+positioning brief** and flag any that would shift it. Sequence by impact ×
+effort.
+
+### 8. Sources / methodology appendix
+The dimensions, weights, rubrics, the scoped set with tiers, source links per
+competitor, and verification notes (asserted vs proven). This is what makes the
+report auditable and defensible — carry the adversarial citation discipline
+through.
+
+## How to present data
+
+- **2×2 / positioning maps** — for landscape and the tension plot. Lead with
+  these; they carry the argument faster than prose.
+- **Heatmap matrix** — for the competitors × dimensions comparison (section 4).
+- **Profile cards** — the source unit feeding deep dives (section 5).
+- **Quadrant callouts** — name who sits in each quadrant explicitly, especially
+  the client's target one.
+- Keep tables scannable; push raw evidence and links to the appendix.
+
+## Decision framework (the report must resolve these)
+
+- **Who do we compete with?** — Name the Direct tier specifically; that's the
+  real fight.
+- **How do we compete?** — State the client's differentiator in one sentence,
+  grounded in the matrix (which dimensions the client owns).
+- **Where are our differentiators defensible?** — Identify the
+  dimensions/quadrant rivals can't easily copy (the moat), vs. the ones that
+  are table-stakes.
+
+## Trigger questions for the team alignment session
+
+End with questions that force decisions, not admiration of the analysis:
+
+- Is the target quadrant truly open, or is a rival already moving in?
+- Which Direct competitor is the sharpest threat in the next 12 months, and
+  what's the counter?
+- Does the brand balance still hold given the landscape — should any emphasis
+  shift?
+- Which dimension where the client trails is worth closing, and which to
+  deliberately concede?
+- What's the one move that most widens distinctiveness *without* costing
+  hireability / credibility?
+
+## Anti-Patterns
+
+- **Leading with methodology.** The executive summary opens with the most important finding, not an explanation of how the benchmark was run. Methodology belongs in the appendix.
+- **Presenting scores without the tension plot.** The 2×2 tension map is the headline artefact. A table of numbers without the map buries the strategic insight.
+- **Omitting the decision framework.** The report must resolve the three questions (who to compete with, how, where the moat is). Leaving these unanswered turns the report into a literature review.
+- **Starting before all profile cards are complete.** Benchmark-methodology must finish before assembly begins. Partial data produces gaps that undermine the heatmap and white-space analysis.
+- **Adding a blended total column to the matrix.** Explicitly excluded — it creates a false composite that obscures the asymmetry the client needs to act on.
+
+## Related Skills
+
+- `benchmark-methodology` — the prerequisite; produces the scored competitor profile cards this skill assembles.
+- `competitive-platform-analysis` — provides the tier structure (Direct / Adjacent / Aspirational) used in Section 3.
+- `brand-discovery` — use to establish the client's positioning brief if it hasn't been defined.

package/prisma/skills/compose-multiplatform-patterns/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: compose-multiplatform-patterns
+description: Compose Multiplatform and Jetpack Compose patterns for KMP projects — state management, navigation, theming, performance, and platform-specific UI.
+metadata:
+  origin: ECC
+---
+
+# Compose Multiplatform Patterns
+
+Patterns for building shared UI across Android, iOS, Desktop, and Web using Compose Multiplatform and Jetpack Compose. Covers state management, navigation, theming, and performance.
+
+## When to Activate
+
+- Building Compose UI (Jetpack Compose or Compose Multiplatform)
+- Managing UI state with ViewModels and Compose state
+- Implementing navigation in KMP or Android projects
+- Designing reusable composables and design systems
+- Optimizing recomposition and rendering performance
+
+## State Management
+
+### ViewModel + Single State Object
+
+Use a single data class for screen state. Expose it as `StateFlow` and collect in Compose:
+
+```kotlin
+data class ItemListState(
+    val items: List<Item> = emptyList(),
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val searchQuery: String = ""
+)
+
+class ItemListViewModel(
+    private val getItems: GetItemsUseCase
+) : ViewModel() {
+    private val _state = MutableStateFlow(ItemListState())
+    val state: StateFlow<ItemListState> = _state.asStateFlow()
+
+    fun onSearch(query: String) {
+        _state.update { it.copy(searchQuery = query) }
+        loadItems(query)
+    }
+
+    private fun loadItems(query: String) {
+        viewModelScope.launch {
+            _state.update { it.copy(isLoading = true) }
+            getItems(query).fold(
+                onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } },
+                onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } }
+            )
+        }
+    }
+}
+```
+
+### Collecting State in Compose
+
+```kotlin
+@Composable
+fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    ItemListContent(
+        state = state,
+        onSearch = viewModel::onSearch
+    )
+}
+
+@Composable
+private fun ItemListContent(
+    state: ItemListState,
+    onSearch: (String) -> Unit
+) {
+    // Stateless composable — easy to preview and test
+}
+```
+
+### Event Sink Pattern
+
+For complex screens, use a sealed interface for events instead of multiple callback lambdas:
+
+```kotlin
+sealed interface ItemListEvent {
+    data class Search(val query: String) : ItemListEvent
+    data class Delete(val itemId: String) : ItemListEvent
+    data object Refresh : ItemListEvent
+}
+
+// In ViewModel
+fun onEvent(event: ItemListEvent) {
+    when (event) {
+        is ItemListEvent.Search -> onSearch(event.query)
+        is ItemListEvent.Delete -> deleteItem(event.itemId)
+        is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery)
+    }
+}
+
+// In Composable — single lambda instead of many
+ItemListContent(
+    state = state,
+    onEvent = viewModel::onEvent
+)
+```
+
+## Navigation
+
+### Type-Safe Navigation (Compose Navigation 2.8+)
+
+Define routes as `@Serializable` objects:
+
+```kotlin
+@Serializable data object HomeRoute
+@Serializable data class DetailRoute(val id: String)
+@Serializable data object SettingsRoute
+
+@Composable
+fun AppNavHost(navController: NavHostController = rememberNavController()) {
+    NavHost(navController, startDestination = HomeRoute) {
+        composable<HomeRoute> {
+            HomeScreen(onNavigateToDetail = { id -> navController.navigate(DetailRoute(id)) })
+        }
+        composable<DetailRoute> { backStackEntry ->
+            val route = backStackEntry.toRoute<DetailRoute>()
+            DetailScreen(id = route.id)
+        }
+        composable<SettingsRoute> { SettingsScreen() }
+    }
+}
+```
+
+### Dialog and Bottom Sheet Navigation
+
+Use `dialog()` and overlay patterns instead of imperative show/hide:
+
+```kotlin
+NavHost(navController, startDestination = HomeRoute) {
+    composable<HomeRoute> { /* ... */ }
+    dialog<ConfirmDeleteRoute> { backStackEntry ->
+        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
+        ConfirmDeleteDialog(
+            itemId = route.itemId,
+            onConfirm = { navController.popBackStack() },
+            onDismiss = { navController.popBackStack() }
+        )
+    }
+}
+```
+
+## Composable Design
+
+### Slot-Based APIs
+
+Design composables with slot parameters for flexibility:
+
+```kotlin
+@Composable
+fun AppCard(
+    modifier: Modifier = Modifier,
+    header: @Composable () -> Unit = {},
+    content: @Composable ColumnScope.() -> Unit,
+    actions: @Composable RowScope.() -> Unit = {}
+) {
+    Card(modifier = modifier) {
+        Column {
+            header()
+            Column(content = content)
+            Row(horizontalArrangement = Arrangement.End, content = actions)
+        }
+    }
+}
+```
+
+### Modifier Ordering
+
+Modifier order matters — apply in this sequence:
+
+```kotlin
+Text(
+    text = "Hello",
+    modifier = Modifier
+        .padding(16.dp)          // 1. Layout (padding, size)
+        .clip(RoundedCornerShape(8.dp))  // 2. Shape
+        .background(Color.White) // 3. Drawing (background, border)
+        .clickable { }           // 4. Interaction
+)
+```
+
+## KMP Platform-Specific UI
+
+### expect/actual for Platform Composables
+
+```kotlin
+// commonMain
+@Composable
+expect fun PlatformStatusBar(darkIcons: Boolean)
+
+// androidMain
+@Composable
+actual fun PlatformStatusBar(darkIcons: Boolean) {
+    val systemUiController = rememberSystemUiController()
+    SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) }
+}
+
+// iosMain
+@Composable
+actual fun PlatformStatusBar(darkIcons: Boolean) {
+    // iOS handles this via UIKit interop or Info.plist
+}
+```
+
+## Performance
+
+### Stable Types for Skippable Recomposition
+
+Mark classes as `@Stable` or `@Immutable` when all properties are stable:
+
+```kotlin
+@Immutable
+data class ItemUiModel(
+    val id: String,
+    val title: String,
+    val description: String,
+    val progress: Float
+)
+```
+
+### Use `key()` and Lazy Lists Correctly
+
+```kotlin
+LazyColumn {
+    items(
+        items = items,
+        key = { it.id }  // Stable keys enable item reuse and animations
+    ) { item ->
+        ItemRow(item = item)
+    }
+}
+```
+
+### Defer Reads with `derivedStateOf`
+
+```kotlin
+val listState = rememberLazyListState()
+val showScrollToTop by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 5 }
+}
+```
+
+### Avoid Allocations in Recomposition
+
+```kotlin
+// BAD — new lambda and list every recomposition
+items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }
+
+// GOOD — key each item so callbacks stay attached to the right row
+val activeItems = remember(items) { items.filter { it.isActive } }
+activeItems.forEach { item ->
+    key(item.id) {
+        ActiveItem(item, onClick = { handle(item) })
+    }
+}
+```
+
+## Theming
+
+### Material 3 Dynamic Theming
+
+```kotlin
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    dynamicColor: Boolean = true,
+    content: @Composable () -> Unit
+) {
+    val colorScheme = when {
+        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
+            if (darkTheme) dynamicDarkColorScheme(LocalContext.current)
+            else dynamicLightColorScheme(LocalContext.current)
+        }
+        darkTheme -> darkColorScheme()
+        else -> lightColorScheme()
+    }
+
+    MaterialTheme(colorScheme = colorScheme, content = content)
+}
+```
+
+## Anti-Patterns to Avoid
+
+- Using `mutableStateOf` in ViewModels when `MutableStateFlow` with `collectAsStateWithLifecycle` is safer for lifecycle
+- Passing `NavController` deep into composables — pass lambda callbacks instead
+- Heavy computation inside `@Composable` functions — move to ViewModel or `remember {}`
+- Using `LaunchedEffect(Unit)` as a substitute for ViewModel init — it re-runs on configuration change in some setups
+- Creating new object instances in composable parameters — causes unnecessary recomposition
+
+## References
+
+See skill: `android-clean-architecture` for module structure and layering.
+See skill: `kotlin-coroutines-flows` for coroutine and Flow patterns.