@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/workflows/code-quality/code-quality-audit.md

@@ -0,0 +1,154 @@
+### Code Quality Audit
+
+Use this workflow for findings-only audit of SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, overengineering, code smell, or violations-check issues in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Do not use this workflow for domain boundaries, bounded contexts, coupling analysis, module depth, seams, adapters, or architecture refactor opportunities. Route those to `workflows/architecture/architecture-audit.md`. Keep local pass-through wrappers, unused speculation, vague names, duplicate literals, and simple overengineering here when the finding does not require architecture-lens evidence.
+
+This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+
+1. Resolve/reuse `workflowSessionId`: `quality-[entity]`
+2. Load shared references:
+   - `references/codebase-investigation.md`
+   - `references/audit-scope.md`
+   - `references/audit-report-io.md` before writing the final direct audit report
+   - `references/context-firewall.md` before inspecting large diffs, logs, snapshots, generated reports, or broad search output
+   - `references/mobile-context.md` when scope includes Android Jetpack Compose or KMP Compose Multiplatform files, source sets, compiler reports, UI tests, screenshot tests, or runtime evidence
+   - `references/naming-standards.md` when evaluating generic names, domain vocabulary, public contract names, or rename recommendations
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected
+   - `references/agent-orchestration.md` only for large scopes, explicit parallel/subagent requests, PR subagent invocation, or independent verification of high-impact findings
+3. `recall` -> load project style rules, ADRs, prior quality decisions, accepted extension points, repeated anti-patterns, and accepted exceptions for the target area.
+   - Apply the Memory Freshness Gate from `references/audit-scope.md`; recalled exceptions are leads, not proof.
+4. Establish the investigation scope before proceeding:
+   - Modified files scope: use when the user says modified files, changed files, current changes, uncommitted changes, staged changes, or unstaged changes.
+   - Explicit files/globs scope: use when the user names files, directories, or globs.
+   - Commit range scope: use when the user provides commits/ranges or asks for commits made by me, my branch commits, or quality issues introduced by branch commits.
+   - Branch comparison scope: use when the user names base/head branches, refs, or a branch diff.
+   - Codebase area scope: use when the user names a path, module, package, feature area, service layer, or glob.
+   - Symbol/class/function scope: use when the user names public classes, functions, interfaces, helpers, or exported surfaces.
+   - Feature/flow scope: use when the user names a runtime flow or feature area.
+   - Whole-repo scope: use only when the user explicitly asks for a whole-repo code quality audit.
+   - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
+   - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
+   - Build the shared scope packet from `references/audit-scope.md` and carry it into the report.
+5. For modified files scope:
+   - Include staged and unstaged tracked files from the working tree.
+   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect maintainability, validation behavior, or public contracts.
+   - Exclude deleted files unless their deletion can break imports, exports, routing, migrations, config, tests, or packaging.
+   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
+   - Inspect diffs first, then only the surrounding code needed to understand quality claims.
+6. For commit range scope:
+   - If the user supplied explicit commits or a revision range, use that exact range.
+   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
+   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
+   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
+   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
+   - Inspect changed files and diffs from those commits, then surrounding code, callers, tests, config, and public API only as needed.
+7. For codebase area scope:
+   - Require a concrete path, module, package, feature area, or glob.
+   - If the target area is missing, ask for it before proceeding.
+   - Follow the shared retrieval order from `references/codebase-investigation.md` to find target modules, semantic hotspots, public API, tests, and adjacent config.
+8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
+   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
+   - For symbol/class/function targets, inspect definitions, references, call sites, tests, and current usage evidence before reporting quality claims.
+   - For feature/flow targets, map the main code path only as far as needed to identify local maintainability or overengineering issues.
+   - If whole-repo scope is requested, report sampled/top-level coverage and skipped deep checks instead of implying exhaustive review.
+9. For implementation parent scope:
+   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, public API, tests, config, and project patterns needed to verify a quality claim.
+   - Return compact findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
+10. Input rules:
+   - SOLID inputs: non-test source files only.
+   - Clean Code inputs: test and non-test source files.
+   - KISS/YAGNI/DRY inputs: test and non-test source files, plus docs/config only when they define behavior or public contracts.
+   - Architecture boundary guard:
+     - Keep local quality issues in this workflow when the fix is delete, inline, rename, extract a constant, collapse a trivial wrapper, simplify control flow, or consolidate duplicated local rules.
+     - Route to `workflows/architecture/architecture-audit.md` when the claim needs bounded-context language, dependency direction, strength/distance/volatility, module depth, seam placement, adapter reality, or cross-domain ownership evidence.
+     - If unsure, report as `suspect` only when concrete local maintainability evidence exists; otherwise recommend an architecture-audit follow-up instead of forcing a CQ finding.
+11. Decide whether to use agent orchestration:
+   - Load it only for large PRs, codebase-wide audits, explicit parallel/subagent requests, or independent verification of judgment-heavy findings.
+   - Keep the audit local for small scopes, unresolved user intent, tightly coupled code without clear owners, or platforms that do not permit subagents.
+   - The main agent still owns scope, memory recall, static leads, synthesis, final report, persistence, and Evidence Gate.
+    - If delegating, dispatch `audit-specialist` with `lens: code-quality` per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: large PR, codebase-wide audit, explicit parallel/subagent request, or independent verification of judgment-heavy finding
+> - scope: bounded read-only slice of the audit target
+> - permissions: read-only
+> - inputs: shared scope packet; `lens: code-quality`; quality dimensions (SOLID, Clean Code, KISS/YAGNI, DRY, maintainability)
+> - sensors: static scans for type-tag branches, concrete construction, half-finished surfaces; source inspection
+> - output: findings with smell category, location, evidence, severity, confidence, and simplest fix direction
+> - firewall: raw diffs/logs/search output summarized, not returned raw
+> - memory: suggest-only; main agent persists reusable code-quality patterns
+
+    - Do not delegate every check by default; avoid duplicate source reading when one main-agent pass is cheaper.
+    - Subagents may suggest memory content, but the main agent decides what durable knowledge to persist.
+12. Gather deterministic leads with static scans where useful:
+   - Type-tag branches: `switch`, `case`, `if/else if`, discriminant fields such as `type`, `kind`, `variant`, `mode`.
+   - Concrete construction: `new [A-Z]` inside class or service bodies.
+   - Half-finished surfaces: `TODO`, `implement later`, exported stubs, `return null`, empty method bodies.
+   - Comments: lines starting with code-restating comments.
+   - Magic values: repeated strings, event names, timeouts, numeric thresholds, status codes.
+   - Generic names: `data`, `info`, `result`, `value`, `temp`, `manager`, `handler`, `helper` without useful qualification, using `references/naming-standards.md` to filter conventional short-scope or framework-required names.
+   - Long parameter lists: more than 3-4 positional parameters.
+   - Needlessly indirect code: pass-through wrappers, one-use abstractions, helper layers with no behavior, factories/builders that only hide one constructor call.
+   - Speculative surfaces: unused options, future-oriented hooks, extension points with one implementation, exported APIs with no evidence of use.
+   - Complexity without payoff: deep nesting, miniature state machines, or polymorphism where a direct branch or data map would preserve clarity.
+   - AI-slop surfaces: generic abstractions with no domain vocabulary, fabricated-looking type names, unnecessary factories/builders, wrappers around one call, comments that narrate obvious code, and broad configurability not supported by current requirements.
+   - Android/KMP Compose recomposition leads: `@Composable`, `remember`, `rememberSaveable`, `derivedStateOf`, `LaunchedEffect`, `DisposableEffect`, `SideEffect`, `produceState`, `snapshotFlow`, `mutableStateOf`, `SnapshotStateList`, stability annotations/config, Compose compiler reports, Compose UI tests, and screenshot tests.
+13. Investigation pass:
+   - Use summary/enriched search, symbol tools, and targeted file reads to inspect target modules, semantic hotspots, public classes, interfaces, functions, and exported API surface.
+   - Apply SOLID checks to non-test source only:
+     - Single Responsibility: flag classes/modules with distinct concern groups, such as validation plus persistence or formatting plus dispatch.
+     - Open/Closed: flag caller-side switches or if/else chains on type tags where adding a variant requires modifying existing files.
+     - Liskov: flag subtypes that throw where the base does not, ignore required methods, or narrow the base contract.
+     - Interface Segregation: flag interfaces that force implementors to define unused methods.
+     - Dependency Inversion: flag hardcoded `new ConcreteType()` inside class bodies where abstraction or injection would be natural.
+   - Apply Clean Code checks to test and non-test source:
+     - Magic values: meaningful bare literals should be named constants, especially repeated strings, timeouts, thresholds, and event names.
+     - Function does more than one thing: if accurate description needs "and", recommend splitting.
+     - Unqualified generic names: flag vague names without domain or role qualification.
+     - What-comments: flag comments that restate code; keep only why comments for constraints, workarounds, or non-obvious invariants.
+     - Half-finished surfaces: flag exported TODOs, stubs, placeholder returns, and "implement later" code.
+     - Long parameter lists: flag more than 3-4 positional parameters; suggest an options object.
+   - Apply KISS/YAGNI/DRY checks:
+     - KISS: flag abstractions, layers, indirection, or control flow that increase cognitive load without clearly improving readability, correctness, or constraint handling. Call out premature generalization, deep call chains, excessive configuration, and clever patterns that obscure intent. Prefer straightforward, explicit code that a new reader can follow end-to-end. Simplify by inlining trivial abstractions, collapsing unnecessary layers, and choosing boring solutions unless complexity is justified (e.g., real variability, hard constraints, or measured bottlenecks).
+     - YAGNI: flag speculative features, extension points, and generic infrastructure that have no concrete caller, requirement, or near-term use. Call out “just in case” hooks, over-parameterization, unused toggles, and frameworks introduced ahead of need. Prefer implementing only what current use cases demand, with code structured so it can evolve when real requirements appear. Defer generalization until duplication or constraints make it necessary, and remove dead or unused paths aggressively.
+     - DRY: flag duplicated logic, data transformations, or domain rules that appear in multiple places without a strong reason (e.g., performance isolation or explicit decoupling). Highlight copy-paste patterns, parallel conditionals, and repeated constants that increase maintenance cost or risk of inconsistency. Recommend consolidation into a single source of truth when it improves clarity and reduces bugs, but avoid over-abstraction that harms readability or introduces indirection for trivial reuse.
+     - Prefer delete, inline, or merge recommendations over replacement abstractions when simpler code preserves behavior.
+     - Require usage evidence before calling a surface unnecessary; if evidence is incomplete, mark the item `suspect`.
+     - Do not recommend ports, adapters, bounded contexts, new service/module boundaries, or VSA migration from this workflow; hand those to architecture-audit.
+   - For Android Jetpack Compose and KMP Compose Multiplatform code, apply recomposition quality checks from `references/mobile-context.md`:
+     - Excessive recomposition risk: unstable parameters, mutable collections or mutable models crossing composable boundaries, expensive work in composition, unremembered lambdas/objects, inappropriate `derivedStateOf`, broad state reads, and backwards writes after state reads.
+     - Missing recomposition or stale UI risk: non-observable mutation, missing or wrong `remember`/effect keys, stale captured lambdas that need `rememberUpdatedState`, incorrect stability annotations, and risky stability configuration entries that can make UX updates fail to happen.
+     - Keep these as `CQ-*` findings only when concrete source evidence ties the pattern to UX jank, stale UI, broken interaction feedback, accessibility/state restoration risk, or maintainability cost.
+     - Mark semantic recomposition claims as `suspect` unless supported by Compose compiler stability/skippability reports, existing Compose UI tests, screenshot tests, benchmark/runtime traces, or a clear deterministic static source pattern.
+     - Verification suggestions should name the cheapest available sensor: Compose compiler metrics/reports, focused Compose UI test, screenshot/golden test, instrumentation/emulator check, or static lint/build command.
+   - For each candidate finding, record the concrete claim, source evidence, impacted maintainability or change-risk flow, provisional severity, and what would disprove it.
+14. False-positive pass:
+   - Try to disprove every candidate before reporting it.
+   - Check framework-required signatures, public SDK or plugin surfaces, ADR-backed extension points, test fixtures/builders, harmless local literals, intentionally tiny adapters, usage evidence, and accepted exceptions.
+   - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark judgment-heavy items as `suspect`.
+15. Severity rules (apply the countable threshold first, then the qualitative clause):
+   - `critical`: quality issue likely causes production outage, data loss, auth/privacy break, OR affects >10 files; otherwise use the qualitative clause below.
+   - `high`: strong SOLID/Clean Code/KISS/YAGNI/DRY violation with high change volatility likely to cause major regression, repeated bugs, or high-cost change friction.
+   - `medium`: real maintainability issue, speculative surface, duplicated rule, weak naming/comment pattern, or avoidable complexity with localized impact (<=10 affected files).
+   - `low`: minor hardening opportunity, low-impact cleanup, incomplete evidence, or weakly supported concern.
+16. Final report:
+   - Findings first, ordered by severity.
+   - Each finding must use `CQ-<N>` and include the canonical fields from `references/audit-report-io.md`: rule, current shape, simplest safe transformation, severity, confidence, file/line, concrete evidence, impact, simplest sufficient fix, and verification suggestion.
+   - For Android/KMP Compose recomposition findings, include whether the risk is excessive recomposition or missing/stale recomposition, the affected composable or state boundary, UX impact, confidence, and the deterministic sensor that would prove or disprove the claim.
+   - Mark judgment-heavy items as `suspect` instead of fact.
+   - Avoid false positives for framework-required signatures, public SDK or plugin surfaces, ADR-backed extension points, test fixtures/builders, harmless local literals, and intentionally tiny adapters.
+   - If a candidate turns on domain language, coupling dimensions, or seam placement, do not force it into `CQ-<N>`; list it as skipped architecture scope or recommend `architecture-audit`.
+   - If no findings, say what scope was checked and which checks were skipped.
+   - Include ruled-out candidates when they were plausible enough to matter.
+   - Include scope checked, deterministic evidence or skipped-check notes, memory outcome, and residual risk.
+   - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `CQ-*` finding or no-finding claim to deterministic sensors, commands/artifacts, results, validation assets, or skipped-check reasons. Model judgment alone cannot satisfy verification/testing all-clear.
+   - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/code-quality/<YYYY-MM-DD code-quality-audit>.md`.
+   - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
+17. Persist only durable knowledge:
+   - Do not persist one-off findings.
+   - Persist repeated anti-patterns, project-specific quality rules, accepted exceptions, or repeated overengineering patterns via `remember` after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:code-quality-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
+18. Complete the Evidence Gate from `references/evidence-gate.md`.

package/skills/massa-ai/workflows/code-quality/code-quality-fix.md

@@ -0,0 +1,99 @@
+### Code Quality Fix
+
+Use this workflow only to execute fixes from a code quality audit markdown report.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not use this workflow for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or overengineering analysis; route that to `workflows/code-quality/code-quality-audit.md`.
+
+1. Resolve/reuse `workflowSessionId`: `code-quality-fix-[entity]`
+2. Load shared references:
+   - `references/audit-report-io.md` before any code change
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/codebase-investigation.md` before changing unfamiliar code
+   - `references/verification-ladder.md` before non-trivial edits
+   - `references/naming-standards.md` before renaming identifiers, introducing domain vocabulary, or changing public contract names
+   - `references/context-firewall.md` before inspecting large diffs, logs, generated reports, or broad search output
+   - `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
+3. `recall` -> load project style rules, accepted quality exceptions, testing conventions, prior anti-patterns, and verification recipes for the report target.
+4. Select the code quality audit report with execution focus:
+   - Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a module, service layer, files/globs, branch comparison, commit range, symbol/class/function, feature/flow, or explicit whole-repo target.
+   - If the user gives a path, read that exact markdown file.
+   - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest code quality report against an unspecified target.
+   - Select the latest `audits/code-quality/<YYYY-MM-DD code-quality-audit>.md` only after target focus is known, using `references/audit-report-io.md`.
+   - Stop if no report exists; do not infer findings from conversation history.
+   - Validate the report with `references/audit-report-io.md`: workflow, `ProjectId`, `Target`, `Target Focus`, scope, git base/head, required fields, `CQ-` IDs, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+5. Extract actionable findings:
+   - Keep findings with concrete `Rule`, `Current Shape`, `Simplest Safe Transformation`, `Location`, `Evidence`, `Impact`, `Simplest Fix Direction`, and `Verification Suggestion`.
+   - Ignore ruled-out candidates, no-finding sections, and `suspect` items unless the user explicitly asks to address suspects.
+   - Treat findings that require bounded-context language, dependency direction, strength/distance/volatility, seam placement, adapter design, or module-depth analysis as invalid for code-quality execution unless the report already reclassified them as local CQ cleanup. Route those to `workflows/architecture/architecture-fix.md` or ask the user to rerun architecture-audit.
+   - If the user supplied finding IDs, extract only those IDs after validating they exist and match the current target focus.
+   - Rank by severity, dependency order, behavior risk, and deletion/simplification payoff.
+6. Build a refactoring map before editing:
+   - Finding ID -> affected code, quality rule, current behavior contract, validation assets, simplest safe transformation, and expected diff shape.
+   - Group duplicate-rule findings only when one small change fixes all of them.
+   - Keep unrelated style cleanup out of scope.
+7. Size each finding with `references/verification-ladder.md`:
+   - Quick: rename, inline, delete unused speculation, extract constant, collapse trivial wrapper, or local parameter-object change.
+   - Standard: multi-file consolidation, shared behavior cleanup, public helper contract change, or meaningful test impact; define characterization checks first.
+   - Spec-driven: broad redesign, unclear behavior, cross-boundary migration, or user-visible behavior change; pause and route to `workflows/spec-driven.md` or ask for approval.
+8. Apply code quality fixing methods:
+   - SOLID: separate mixed responsibilities only when the split reduces change risk; replace caller-side type switches with polymorphism or data maps only when new variants are real; preserve base contracts; narrow fat interfaces; inject dependencies when hardcoded concretes block testing or substitution.
+   - Clean Code: name domain concepts precisely using `references/naming-standards.md`, replace repeated magic values with named constants, split functions that truly do multiple things, remove code-restating comments, finish or delete stubs, and convert long positional parameter lists to options objects when it improves call-site clarity.
+   - KISS: inline shallow helpers, collapse needless layers, choose direct control flow over clever indirection, and remove configuration that hides rather than expresses behavior.
+   - YAGNI: delete unused extension points, future hooks, unused options, one-implementation factories, and speculative public APIs when usage evidence is absent.
+   - DRY: consolidate duplicated domain rules or transformations into one clear source of truth, but avoid abstractions that make trivial duplication harder to read.
+   - AI-slop cleanup: remove generic wrappers, fabricated-looking abstractions, one-call factories, code-restating comments, and unused configurability when current usage evidence does not justify them.
+   - Do not introduce ports, adapters, bounded contexts, new service/module boundaries, or VSA-style folder migration to satisfy a code-quality finding.
+9. Preserve behavior:
+   - Run or identify characterization tests before changing behavior-adjacent code.
+   - Do not weaken tests, fixtures, snapshots, types, or public contracts to make cleanup pass.
+   - Prefer small reversible edits; verify after each finding or coherent group.
+10. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
+> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
+> - scope: one isolated code-quality finding or disjoint file group
+> - permissions: write (disjoint write set)
+> - inputs: the finding ID, smell category (SOLID/Clean Code/KISS/YAGNI/DRY), location, and simplest fix direction
+> - sensors: report's verification suggestion or equivalent deterministic command; behavior-preservation check
+> - output: implementation summary, commands run, test counts, deviations
+> - firewall: raw diffs/logs summarized
+> - memory: suggest-only; main agent persists reusable code-quality patterns
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: independent verification of a high-risk code-quality fix
+> - scope: the fixed finding's behavior preservation, imports, tests, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
+> - sensors: deterministic command (behavior-preservation check, import graph, tests) and report claim closure
+> - output: confirmed/disproven closure verdict with evidence
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+   - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+11. Verify each completed finding:
+   - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+   - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
+   - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+   - Run the report's verification suggestion when available.
+   - Run targeted tests, type checks, lint/static checks, or import checks relevant to touched files.
+   - Perform a focused diff review for touched identifiers and confirm generic names are either replaced with precise domain/role names or justified by narrow conventional scope.
+   - Check validation assets were not weakened unless explicitly requested.
+   - Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
+12. At completion, persist only durable knowledge:
+   - Repeated anti-patterns, accepted quality exceptions, project-specific refactoring recipes, or reusable checks after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:code-quality-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
+13. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Use code-quality-fix to fix latest findings for billing services."
+
+1. Confirm target focus is `billing services`, then read the latest matching `audits/code-quality/* code-quality-audit.md`.
+2. Validate metadata, target focus, freshness, required fields, and current evidence before editing.
+3. Execute confirmed non-suspect findings by severity and behavior risk.
+4. Prefer delete/inline/rename/extract before introducing new abstractions.
+5. Verify behavior and validation assets after each finding group.

package/skills/massa-ai/workflows/commit.md

@@ -0,0 +1,61 @@
+### Commit
+
+Use this workflow when the user wants to draft a commit message, prepare a commit, or commit current repository changes. This workflow adapts the local caveman-commit rules into a safe Git workflow for changed files.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Do not use this workflow for Jira ticket creation, release notes, changelogs, PR descriptions, or history rewriting. Route Jira issue work to `workflows/ticket.md`. Route broad release documentation to the relevant feature, RFC, or general workflow.
+
+## Workflow
+
+1. Resolve or reuse `projectId` and `workflowSessionId=commit-<entity>`.
+2. Run `recall` for durable project commit conventions, branch naming patterns, and attribution requirements. Treat recalled conventions as leads until current repository evidence confirms them.
+3. Inspect current Git state before writing a message:
+   - current branch from `git rev-parse --abbrev-ref HEAD`
+   - staged paths from `git diff --cached --name-only`
+   - unstaged changed paths from `git diff --name-only`
+   - status summary from `git status --short`
+   - staged diff when anything is staged; otherwise the unstaged diff for allowed paths
+4. Extract the first Jira key from the branch with case-insensitive regex `(?<![A-Z0-9])([A-Z][A-Z0-9]{1,9}-[0-9]+)(?![A-Z0-9])`. Normalize the key to uppercase. If no key is found, proceed without a prefix and do not ask.
+5. Resolve commit scope:
+   - If files are already staged, treat staged files as the user-selected commit scope and do not stage additional files.
+   - If nothing is staged and the user explicitly asked to commit, stage only allowed changed files one path at a time with pathspec-safe commands.
+   - If the user asked only for a message, do not stage or commit. Output the message in a code block plus any excluded paths.
+6. Exclude audit report Markdown files from commit scope:
+   - any Markdown file under `audits/`
+   - any Markdown basename matching `*-audit.md`
+   - If any excluded file is already staged, stop before committing and report the exact paths. Do not unstage user-selected files unless the user explicitly asks.
+7. Never stage everything through a shortcut, never commit all tracked modifications automatically, and never reset, checkout, amend, squash, rebase, or rewrite history unless the user separately requests that exact operation.
+8. Draft the commit message using caveman-commit rules:
+   - Conventional Commits format: `<type>(<scope>): <imperative summary>`, with scope optional.
+   - Type precedence when multiple apply: `fix`, `feat`, `perf`, `refactor`, `test`, `docs`, `build`, `ci`, `style`, `chore`, `revert`. Use `revert` only when the commit's primary purpose is reverting an earlier change.
+   - Subject is imperative, has no trailing period, targets 50 characters when practical, and has hard cap 72 characters including any Jira prefix.
+   - With a Jira key, prefix the subject exactly as `[<KEY>] `, for example `[SA-142] fix(auth): reject expired tokens`.
+   - Match existing project capitalization after the colon when current history or nearby commits make it clear.
+   - Body is required for breaking changes, migrations, security fixes, reverts, linked issues, or rationale not inferable from the diff. Wrap body lines at 72 characters.
+   - Do not include AI attribution unless the repository explicitly requires an attribution trailer.
+9. If committing, run the commit with the exact drafted message only after the final staged-path audit report exclusion check passes. If the commit fails, report the exact failure and leave staging untouched.
+10. Complete `references/evidence-gate.md`, including branch key detection result, staged path policy, excluded audit Markdown paths, command outcome, skipped checks, memory outcome, and residual risk.
+
+## Failure Handling
+
+- No changes: stop and report that there is nothing to commit.
+- Only excluded audit Markdown changed: stop and report excluded paths; do not create an empty commit.
+- Detached HEAD or unreadable branch: proceed without Jira prefix and report the branch state.
+- Ambiguous commit type: use the type precedence list; ask only if two candidate types would materially change downstream release behavior.
+- Excluded file already staged: stop before committing and report the exact staged audit Markdown paths.
+- Commit command fails: report the failure, do not retry unchanged more than once, and do not alter staging to force success.
+
+## Examples
+
+User asks: "Use the commit workflow and commit this."
+
+Actions: inspect branch and staged state, stage only allowed changed files if none are staged, exclude audit Markdown, generate a concise Conventional Commit message, add Jira prefix if branch contains a key, run the commit, then report evidence.
+
+User asks: "Write a commit message."
+
+Actions: inspect diff and branch, generate the message in a code block, list excluded audit Markdown paths, and do not stage or commit.
+
+User asks: "Commit everything, but leave audit reports out."
+
+Actions: stage allowed changed files individually, exclude `audits/**/*.md` and `*-audit.md`, stop if an excluded file is already staged, and commit only the allowed scope.

package/skills/massa-ai/workflows/debug.md

@@ -0,0 +1,86 @@
+### 🔴 Debug
+
+Use this workflow when the user reports broken behavior, failures, regressions, crashes, unexpected output, flaky behavior, or any issue that needs evidence-backed root-cause diagnosis before a fix. Do not use it for new capabilities; route that to `workflows/feature.md`. Do not use it for broad redesign or unclear cross-boundary changes; route that to `workflows/spec-driven.md`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+1. Generate/reuse `workflowSessionId`: `debug-[entity]`
+2. Load shared references:
+   - `references/codebase-investigation.md`
+   - `references/debug-diagnosis-loop.md`
+   - `references/mobile-diagnosis.md` when the bug target involves KMP, iOS, Android, native bridges, devices, simulators/emulators, or mobile lifecycle
+   - `references/verification-ladder.md` before Quick/Standard/Spec-driven sizing or applying fixes
+   - `references/context-firewall.md` before inspecting logs, traces, snapshots, or generated output that meet its threshold table (a single source/log/doc block >200 lines, >20 KB, or >50 search hits)
+   - `references/lessons.md` when `.specs/lessons.json` exists, to load confirmed project lessons before diagnosis
+3. `recall` → load prior debugging attempts for this entity
+4. IF prior attempts exist:
+   - Review what was already tried
+   - Focus on untested hypotheses
+   - Treat memories tagged `stale` or superseded by `stale-replaces:*` as historical only
+   - Do not repeat ruled-out hypotheses unless new evidence invalidates the prior result
+5. Follow the shared retrieval order from `references/codebase-investigation.md`
+   to load relevant code. `optimized_context` has no session field; put
+   `workflowSessionId` in query text/tags and pass only `synapseSessionId` to
+   `search.sessionId`.
+   - For large files (>200 lines) or derived-value computation, call `execute_file` with `path`, `language`, and `code` to run analysis code over the file instead of loading the entire file into context. Respect the local-dev-only trust model (no untrusted-client exposure).
+   - After opening a file for deep investigation, call `synapse_prefetch` with `id` (the `synapseSessionId`) and `filePath` to warm the Synapse buffer before the next search. Requires an existing `synapse_session` id.
+6. Build or request a trustworthy feedback loop before editing:
+   - Use the reproduction ladder in `references/debug-diagnosis-loop.md`: unit/CLI repro, integration/API repro, app/browser/device repro, then structured HITL.
+   - IF no loop can run, record a skipped-reason enum from the debug reference and collect the strongest root-cause proof available
+7. Reproduce and minimize the user-described failure without losing the original failure signal
+8. Rank 3-5 falsifiable hypotheses before testing:
+   - include evidence, prediction, probe, disproof criteria, and tested result
+   - test one hypothesis at a time; instrument only to answer the current hypothesis
+   - for flaky failures, measure and improve reproduction rate before root-cause guessing
+9. Apply debugging heuristics (see `references/decision-engine.md`):
+   - Trace data flow: input → transformation → output
+   - Compare expected vs actual behavior
+   - Check recent changes first
+   - Minimize search space to relevant modules
+   - For call/data-flow path tracing, call `trace_path` with `function_name` (or `qualifiedName`), `project`, `direction` (outbound/inbound/both), `mode` (calls/data_flow/cross_service/all), and `depth` to trace typed-edge BFS paths. `trace_path` only counts as evidence when the index is fresh for the current repository path and commit/worktree state; fall back to `search`/`get_references` and record reduced retrieval confidence when the index is stale or unavailable.
+10. Size the fix before editing:
+   - Use the exact Quick, Standard, and Spec-driven thresholds in `references/verification-ladder.md`.
+   - Refactor route applies only when the fix becomes behavior-preserving cleanup after the root cause is proven.
+11. Define the verification recipe before changing code:
+   - reproduction or root-cause proof
+   - commands, tests, or artifact checks that prove the fix
+   - file-integrity checks for validation assets such as tests, specs, benchmarks, fixtures, and snapshots
+12. Fix the divergence point closest to the root cause
+13. Add regression coverage at the correct seam, or document why no valid regression seam exists
+14. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+     Rerun the original feedback loop, run the verification recipe, and remove temporary instrumentation unless intentionally retained as observability
+15. Use `references/agent-orchestration.md` only for independent verification or isolated investigation branches
+16. IF fix found:
+   - Persist the root cause via `remember` as a scored `decision` memory with `memory:semantic`
+   - Persist the fix pattern via `remember` as a scored `pattern` memory with `memory:procedural`
+   - If a prior debugging memory for this entity is now stale or contradicted by the fix, call `memory_update` with its `id` and the corrected `content` (re-embeds automatically)
+17. IF NOT resolved:
+   - Persist what was ruled out via `remember` as a scored `conversation` memory with `memory:episodic`
+   - Persist repeated failed tool loops as procedural cognition lessons only when they are reusable
+   - Document remaining hypotheses for future sessions
+18. Complete the Evidence Gate from `references/evidence-gate.md`
+
+## Output Contract
+
+- Issue Summary: symptom, impact, frequency, and environment
+- Feedback Loop: command, tool, artifact, or root-cause proof that showed failure and then success
+- Hypothesis Board: ranked hypotheses and tested results
+- Root Cause: evidence-backed diagnosis with the divergence point
+- Fix + Validation: code/test strategy, verification recipe, and commands or artifacts checked
+- Prevention: regression test, monitor/runbook suggestion, and memory outcome
+- For mobile bugs: device matrix, platform parity, crash/log artifact, and impacted/unaffected platform validation
+
+## Example
+
+User asks: "The login route returns 500 after deploy."
+
+1. Use `workflowSessionId=debug-login-route-500` and recall `session:debug-login-route-500 login route 500 prior attempts`.
+2. If recall says "session expiry was ruled out on 2026-05-30", do not repeat that hypothesis unless new evidence contradicts it.
+3. Establish the feedback loop: reproduce the 500 with the smallest route check that preserves the deploy failure signal.
+4. Build a hypothesis board: missing env, middleware ordering, expired session lookup, or database connection regression; probe one at a time.
+5. Trace request → auth middleware → session lookup → response, then fix the divergence point closest to the root cause.
+6. Define the verification recipe: rerun the original route check, add or update regression coverage at the failing seam, and confirm validation assets were not weakened.
+7. If root cause is a missing `DATABASE_URL`, persist via `remember`: a semantic decision memory for the root cause and a procedural pattern memory for the deploy-env verification command.

package/skills/massa-ai/workflows/design.md

@@ -0,0 +1,54 @@
+### Design
+
+Use this workflow to implement or update a concrete Android, iOS, or KMP Compose Multiplatform UI from structured Figma evidence or supplied screenshot context when no saved mobile Figma audit report is the source of truth. Route findings-only comparison to `mobile-figma-audit` and saved `MFM-*` remediation to `mobile-figma-fix`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not use this workflow for Flutter, React Native, web UI, generic Figma exploration, variable-only queries, or MCP troubleshooting.
+
+1. Resolve/reuse `workflowSessionId`: `design-[entity]`.
+2. Load `references/mobile-figma-matcher/repository-detection.md`, `references/mobile-figma-matcher/core.md`, `references/mobile-context.md`, `references/codebase-investigation.md`, and `references/verification-ladder.md`. Load `references/context-firewall.md` before large design/runtime artifacts and `references/synapse-policy.md` when repeated massa-ai searches are expected.
+3. `recall` -> load current component conventions, design-system rules, approved platform/accessibility deviations, prior Figma mappings, asset pipelines, and reusable render recipes. Memory is context, not proof.
+4. Require a concrete feature/module target plus at least one design source: readable Figma node/selection or supplied screenshots. Resolve required visual and interactive states plus a requirements source for behavior not represented in the design source. Ask only when target ownership, runtime platforms, platform-frame mappings, or screenshot authority remain ambiguous after source inspection.
+5. Build the immutable Target Surface Packet before loading stack guidance. Classify each selected surface and load only its contracts:
+   - Android Views XML -> `references/mobile-figma-matcher/android-views.md`.
+   - Android Jetpack Compose -> `references/mobile-figma-matcher/android-compose.md`.
+   - iOS UIKit -> `references/mobile-figma-matcher/ios-uikit.md`.
+   - iOS SwiftUI -> `references/mobile-figma-matcher/ios-swiftui.md`.
+   - Shared KMP Compose Multiplatform -> `references/mobile-figma-matcher/kmp-compose-multiplatform.md` plus native contracts only for selected native source sets, hosts, wrappers, or runtime targets.
+6. Build the Figma Evidence Packet with metadata when needed, design context, screenshot, variables, current Code Connect mappings, variants/states, annotations, and asset inventory. For screenshot-only sources, build a Screenshot Context Packet with provenance, target state, visible constraints, uncertainty, and `Design Evidence Class: screenshot-context-only`; do not infer exact Figma tokens, dimensions, variables, variants, or parity from screenshots alone. Stop if neither structured Figma evidence nor supplied screenshot context is available.
+7. Resolve current components, tokens, resources, assets, source-set ownership, platform adapters, requirements, and existing validation sensors. Create the Design-To-Code Mapping Matrix and one comparison configuration for every selected runtime surface; screenshot-only rows must use inferred visual intent rather than `Figma Value`.
+8. Size the work with the Verification Ladder. Route broad application work, unresolved architecture, cross-feature design-system migration, or implementation that will not fit one clean context window to `spec-driven`.
+9. Establish the verification recipe before editing. Protect tests, snapshots, screenshot baselines, fixtures, previews, accessibility identifiers, test tags, and automation flows from weakening.
+10. Implement coherent slices using the smallest correct ownership boundary:
+    - Reuse existing components and tokens only after resolving semantics, states, accessibility, and values.
+    - Save required temporary Figma-served assets into the repository's existing durable asset pipeline before referencing them.
+    - Keep shared KMP UI in common source sets only when ownership is genuinely shared; keep platform UI and adapters explicit.
+    - Apply shared KMP root fixes before platform-local overrides when the cause is shared.
+    - Preserve platform accessibility, safe areas/insets, localization, adaptive behavior, and native conventions.
+11. After each coherent slice, rebuild affected mapping/comparison rows and run the cheapest deterministic sensors. When a shared KMP change affects Android and iOS, verify both requested targets or mark the unavailable platform `NOT EVALUATED`.
+12. Refresh the Figma node, when available, and all selected target surfaces before completion. Completion requires zero unresolved selected `MISMATCH` rows for structured Figma evidence; `NOT EVALUATED` rows remain explicit residual risk and prohibit complete parity claims. Screenshot-only completion may claim implementation against supplied screenshot context, never exact Figma parity.
+13. Report changed files, final per-surface matrix, saved assets, strongest verification level, skipped checks, and residual risk.
+14. Persist only durable token/component mappings, approved deviations, source-set ownership rules, asset-pipeline rules, or reusable render recipes after Importance Calibration. Use `workflow:design` and required project/session/entity/memory tags.
+15. Complete `references/evidence-gate.md`. Model visual judgment alone cannot satisfy completion.
+
+## Examples
+
+User asks: "Implement this Figma checkout screen in the app's SwiftUI module."
+
+1. Detect the Xcode target and SwiftUI surface from build and source evidence.
+2. Load the shared core plus SwiftUI contract, map Figma states to current styles/views/assets, implement, and verify with existing previews, snapshots, XCTest/XCUITest, or simulator sensors.
+
+User asks: "Build this screen in our KMP app for Android and iOS."
+
+1. Detect whether UI is shared Compose Multiplatform or native per platform.
+2. Load the KMP contract for shared composables and add Android Compose, Android Views, UIKit, or SwiftUI contracts only for actual hosts/source sets.
+3. Verify shared source once and runtime parity separately for Android and iOS.
+
+User asks: "Use this screenshot as context for the Android settings screen."
+
+1. Classify screenshot context, target surface, and uncertainty before editing.
+2. Implement only visible/in-scope intent and preserve behavior requirements from separate sources.
+3. Report that exact Figma parity, tokens, and variables were not evaluated.

package/skills/massa-ai/workflows/exploration.md

@@ -0,0 +1,119 @@
+### 🔵 Exploration
+
+Use this workflow when the user wants to understand a codebase, module, data flow, runtime behavior, schema, dependency, or architecture area before asking for changes. Exploration is read-only: do not implement, refactor, rewrite docs, or mutate project files unless the user explicitly changes workflows or asks for edits.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+## Golden Rules
+
+Inviolable across every exploration:
+
+1. **Never assume or invent.** Uncertainty is always preferable to fabrication; invented APIs, symbols, or patterns cascade into wrong answers.
+2. **Deserves-a-note.** When understanding is worth persisting, record what is durable — not trivia.
+3. **Pointers, not copies.** Link/reference source (`path`, symbol, line); do not duplicate bulk content into notes or reports.
+4. **Surgical precision.** Make the smallest sufficient change; in Exploration, that usually means the smallest sufficient read set.
+5. **Verify against source.** Treat indexed context, memories, and external summaries as leads until confirmed against current source.
+
+Write and search in the user's human language. Match the language of the user's prompt for explanations, notes, and questions; match the language of the codebase for identifiers, paths, and commands.
+
+## Knowledge Verification Chain
+
+When researching or resolving any technical question during exploration, follow this chain in strict order. Never skip steps.
+
+```
+Step 1: Codebase → existing code, conventions, patterns already in use
+Step 2: Project docs → README, docs/, inline comments, .specs/project/STATE.md (Decisions)
+Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
+Step 4: Web search → official docs, reputable sources, community patterns
+Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"
+```
+
+- If a chain step's tool is unavailable (Context7 MCP not registered, no web
+  access), record it as a skipped sensor with its reason and continue to the next
+  step. An unavailable step is skipped, never silently treated as answered.
+- Never skip to Step 5 if Steps 1-4 are available.
+- Step 5 is always flagged uncertain — never presented as fact.
+- Never assume or fabricate. If no answer is found, say "I don't know" or "I couldn't find documentation for this". "I don't know" beats invention.
+
+1. Resolve/reuse `projectId` and `workflowSessionId`: `explore-[entity]`.
+2. Load shared references:
+   - `references/codebase-investigation.md` always.
+   - `references/context-firewall.md` when source inspection, logs, traces, snapshots, generated output, external research, or broad search results may flood context.
+   - `references/synapse-policy.md` when two or more related massa-ai searches are expected.
+   - `references/mobile-context.md` only for non-debug mobile exploration involving KMP, iOS, Android, native bridges, mobile lifecycle, offline sync, permissions, push/background work, local persistence, backend-mobile contracts, or runtime lazy loading.
+   - `references/agent-orchestration.md` only when an isolated read-only investigation or independent verification task is justified.
+   - Route broken mobile behavior, crashes, regressions, or device-specific failures to `workflows/debug.md` plus `references/mobile-diagnosis.md`; do not keep them in Exploration.
+3. Brief the exploration:
+   - objective and user-facing success criteria
+   - scope and explicit out-of-scope areas
+   - constraints, target environment, and current session
+   - whether the task is pure explanation, onboarding, flow mapping, or decision support
+4. Recall first:
+   - `recall` for prior decisions, patterns, handoffs, gotchas, and previous exploration of the entity.
+   - Filter stale, superseded, or contradicted memories before using them as current truth.
+   - Treat memory as a lead until confirmed against current source when accuracy matters.
+5. Build a proportional investigation plan before deep reads (BRIEFING → PLAN → EXECUTE → DEBRIEF):
+   - start from the closest entry point to the question
+   - name the symbols, files, routes, commands, docs, or runtime artifacts to inspect
+   - per step, state a `verify:` criterion — what concrete evidence confirms that step succeeded (a read signature, a matched call graph, a resolved data path) before moving on
+   - define what evidence would be enough to answer the user
+   - ask only if the objective or scope cannot be inferred from local context
+6. Recon with progressive disclosure. Dispatch `investigator` per `references/agent-orchestration.md` when the investigation justifies an isolated read-only subagent:
+
+> **Dispatch: `massa-ai-investigator`** (role: `investigator`) — charter `skills/agents/investigator/SKILL.md`
+> - trigger: isolated read-only investigation justified; large scope, repeated searches, or context-firewall threshold exceeded
+> - scope: the exploration target — symbols, files, routes, commands, docs, or runtime artifacts to inspect
+> - permissions: read-only
+> - inputs: objective, scope, explicit out-of-scope areas, constraints, recalled facts, and the closest entry point
+> - sensors: progressive disclosure (project map → summary search → enriched search → symbol/file tools → optimized context → focused shell); per-step `verify:` criterion
+> - output: entry points, core flow, dependencies, data ownership, relevant contracts, exact evidence pointers (path, symbol, line), confirmed facts vs inferences
+> - firewall: raw logs, snapshots, generated reports, and broad search output summarized, not returned raw
+> - memory: suggest-only; main agent persists durable discoveries
+
+    - Follow the shared retrieval order: project map, summary search, targeted
+      enriched search, symbol/file tools, optimized context, then focused shell
+      fallback.
+   - When external documentation, API references, or web content is needed to answer the question, call `fetch_and_index` with `url` (or `requests`[]) to fetch, convert HTML→markdown or extract JSON key-paths, and index the result into the searchable store so it can be retrieved later via `search`. SSRF-guarded, TTL-cached.
+   - Follow imports, calls, ownership boundaries, and data paths from entry point outward.
+   - For behavior questions, trace input -> transformation -> output.
+   - Read signatures and high-value logic first; avoid whole-project sweeps and large raw file reads.
+   - Use pointers (`path`, symbol, line) instead of copying code into notes or reports.
+7. Mobile exploration extension:
+   - Capture only the minimal mobile packet needed: platform scope, shared vs platform boundary, parity target, relevant device/runtime state, and cheapest validation sensor.
+   - For runtime lazy-loading questions, trace list/media/module loading, cache and prefetch behavior, lifecycle or background constraints, offline behavior, and Android/iOS parity where relevant.
+   - State skipped platform checks and the risk of treating one platform or simulator as global proof.
+8. Synthesize the answer:
+   - state what was checked and what was intentionally not checked
+   - identify entry points, core flow, dependencies, data ownership, and relevant contracts
+   - include exact evidence pointers: file paths, symbols, commands, or artifacts
+   - separate confirmed facts from inferences and open questions
+   - name the next best workflow if the user wants changes after the explanation (`debug`, `feature`, `refactor`, `architecture-audit`, `spec-driven`, etc.)
+9. Debrief memory with scoring from `references/decision-engine.md`:
+   - Persist only durable discoveries that would cost future effort to rediscover: repeated project patterns, architectural constraints, fragile flows, gotchas, accepted exceptions, rejected approaches, or reusable verification recipes.
+   - **Note-worthiness trigger:** when understanding touches 3+ files or a non-trivial flow, persist a note to the massa-ai memory layer. Below that threshold, decide per-finding.
+   - Three-way note decision: **create** (new durable finding), **update** (existing non-stale note for the same entity), or **skip** (trivial, one-off, already captured). The Debrief records what was verified against source, not just what was read.
+   - Use `remember` with required tags and the correct memory tier.
+   - Keep `massa-ai` as the canonical memory layer for massa-ai workflows. Do not introduce `.notebook/`, generated state files, or copied-code notes as default persistence.
+   - Skip memory for trivial observations, one-off facts, raw logs, copied source, screenshots, customer data, tokens, device IDs, and facts already captured in current non-stale memories.
+10. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Anti-Patterns
+
+- Reading the entire project when a nearby entry point exists.
+- Dumping raw logs, browser snapshots, generated reports, long diffs, or whole files into context.
+- Treating stale or superseded memories as current source truth.
+- Implementing fixes or refactors inside Exploration.
+- Creating a new persistence system or duplicating local notebook files inside massa-ai workflows.
+- Asking the user where code lives before searching current sources.
+
+## Output Contract
+
+- Objective: what question was answered
+- Scope Checked: files, symbols, docs, commands, memories, or artifacts inspected
+- Entry Points: closest source pointers for future navigation
+- Flow: input -> transformation -> output, when applicable
+- Key Evidence: exact paths, symbols, command results, or artifact pointers
+- Mobile Context: platform, boundary, parity, and skipped checks when mobile context was loaded
+- Confirmed Facts vs Inferences: label uncertainty explicitly
+- Next Step: recommended workflow if the user wants changes
+- Memory: write/skip, memory tier, and reason