@mriekki/lean 0.4.2 → 0.4.4

package/assets/generated/core/core/skills/db-lab/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: db-lab
+description: "Optional project-aware database learning lab using actual schema, ORM, migration, query, and query-plan evidence for SQL, relational design, debugging, change exploration, and interview practice."
+argument-hint: "[schema|changes|trace|plan|debug|migration|interview|topic] [work-item] [light|focused|deep]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Database Lab
+
+`/db-lab` is an optional hands-on database learning surface. It complements `/coach`; it does not replace the engineering workflow or authorize implementation changes.
+
+For detailed usage and examples, read `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer (or the canonical `core/process/DATABASE_LEARNING_WORKBENCH.md`).
+
+## 1. Boundaries
+
+- Start from the **current** repository and its documented development/test database configuration.
+- Re-discover relevant database evidence whenever the lab is invoked. Running `/db-lab` means inspect current evidence and show the current view; do not make the human remember to refresh/rebuild an ERD.
+- Prefer read-only inspection. Do not mutate application data, apply migrations, add/drop indexes, or change production code while in Database Lab mode.
+- Never inspect Production credentials or Production data.
+- Do not invent schema, SQL, query-plan behavior, ORM translation, or index usage. Distinguish inferred behavior from captured evidence.
+- If safe local database/runtime evidence is unavailable, fall back to repository artifacts and say what could not be verified.
+- Generated learning artifacts are disposable projections of current evidence. Generate in temp/cache output and do not commit them unless explicitly requested.
+- Discovered implementation defects return to the normal engineering workflow; do not silently fix them here.
+- Learning is optional and never blocks delivery.
+
+## 2. Database competencies
+
+Use the common L1-L6 learning levels across independent database areas:
+
+```text
+relational modeling
+keys + integrity constraints
+normalization + data anomalies
+SQL query construction
+indexes + access patterns
+query plans + performance reasoning
+transactions + concurrency
+ORM translation + abstraction leaks
+schema evolution + migrations
+database debugging
+design defense + interview communication
+```
+
+Do not collapse these into one generic "SQL level". A developer may be strong in query syntax and weak in relational design, indexing, transactions, or ORM translation.
+
+## 3. Schema mode
+
+Build an evidence-backed current view from the best available sources:
+
+```text
+physical database metadata
+ORM model/configuration
+migration history
+schema SQL / DDL
+project architecture and requirements
+```
+
+Show tables/entities, columns, types, nullability, primary keys, foreign keys, unique/check constraints, indexes, relationship cardinality, cascade behavior, and relevant ORM mappings when evidence exists.
+
+When useful, distinguish:
+
+```text
+DOMAIN MODEL   — what the application/domain expresses
+ORM MODEL      — what the ORM maps and tracks
+PHYSICAL MODEL — what the relational database actually stores/enforces
+```
+
+## 4. Change-focused mode
+
+`/db-lab changes <work-item>` should focus on the accepted/delivered change set when evidence is available.
+
+Show relevant changes to:
+
+- entities/tables and columns;
+- keys, constraints, relationships and cascade behavior;
+- indexes/access paths;
+- ORM mappings and generated SQL behavior;
+- migrations/schema evolution;
+- affected query paths;
+- transaction/concurrency assumptions.
+
+Connect each material change to the learning implication. A changed ORM/model file is evidence that persistence code was touched, not proof that the physical database changed; verify against migrations/schema/database evidence.
+
+When a previous disposable workbench snapshot exists, it may be used as a comparison aid. The current database/repository evidence remains authoritative.
+
+## 5. Query trace mode
+
+Trace a real application query without guessing:
+
+```text
+application/ORM expression
+→ ORM translation preview when available
+→ actual executed SQL when captured
+→ parameters
+→ tables/relationships touched
+→ query plan when available
+→ indexes actually chosen by the planner
+→ materialized/application result
+```
+
+Keep translation preview and actual executed command distinct when the framework exposes both.
+
+## 6. Query-to-ERD highlighting
+
+When the distributed SQLite workbench or another compatible viewer is available, a selected query should drive a linked ERD view:
+
+- highlight tables referenced by the SQL;
+- highlight FK edges when both related tables participate in the selected query;
+- highlight qualified query columns when they can be resolved to a table;
+- distinguish candidate indexes from indexes actually selected by the query planner;
+- show query-plan evidence alongside the diagram;
+- allow table/column/index selection for deeper explanation.
+
+Never claim the planner used an index merely because it exists or looks relevant.
+
+If no interactive viewer is available, provide a temporary Mermaid/text diagram using the same evidence and clearly label it as a fallback rather than a live ERD.
+
+## 7. SQLite workbench
+
+When `tools/lean-db-lab/sqlite-workbench.py` exists and a safe local development/test SQLite database is known, prefer it for physical-schema and query-plan evidence.
+
+The tool:
+
+- opens the SQLite database in `mode=ro`;
+- introspects tables/views, columns, primary keys, foreign keys, indexes, and DDL;
+- accepts optional captured-query JSON containing `name`, `sql`, and optional `parameters`;
+- uses `EXPLAIN QUERY PLAN` only for `SELECT`/`WITH` queries;
+- generates self-contained `index.html` plus `workbench.json` learning artifacts;
+- supports interactive table/index inspection and query-to-ERD highlighting.
+
+Generate output in a stable per-repository disposable/temp location when practical. Running the lab should regenerate the current view; an already-open older browser tab is not authoritative.
+
+The workbench analyzes captured SQL; it does not itself capture Entity Framework commands. Obtain translation/execution evidence through supported framework mechanisms first, then pass the captured SQL into the workbench when useful.
+
+## 8. Query-plan/performance mode
+
+Use provider-native plan evidence where safely available. Ask the developer to predict likely scans/searches/joins/index behavior before revealing the plan when that improves learning.
+
+```text
+query/access pattern
+→ developer prediction
+→ plan evidence
+→ explain scan/search/join behavior
+→ developer proposes index/query change
+→ predict changed plan
+→ compare evidence in a safe sandbox when available
+```
+
+Do not teach "add an index" without connecting it to a concrete access pattern, selectivity/order needs, write cost, and plan evidence.
+
+## 9. Debug mode
+
+```text
+symptom
+→ database hypotheses
+→ distinguishing evidence
+→ SQL / parameters
+→ plan / constraints / transaction state
+→ root cause
+→ fix concept
+→ prevention
+```
+
+The human should diagnose before the lab reveals the answer unless they explicitly request explanation-first coaching.
+
+## 10. Migration mode
+
+Connect:
+
+```text
+ORM migration/change
+↔ generated DDL/SQL when available
+↔ schema before
+↔ schema after
+↔ data-safety implications
+```
+
+Ask the developer to predict effects before showing generated SQL when useful. Discuss destructive changes, nullability transitions, backfills, constraint creation, and rollback limitations without applying migrations in learning mode.
+
+## 11. Interview/design mode
+
+Use the active project domain as context, but perturb requirements so the developer must reason rather than reproduce the existing schema.
+
+Drive one material question at a time through:
+
+```text
+requirements clarification
+→ entities
+→ relationships/cardinality
+→ keys
+→ constraints
+→ normalization
+→ access patterns
+→ indexes
+→ transactions/concurrency
+→ evolution/scaling
+→ design defense
+```
+
+Challenge unsupported choices. Ask why a junction table exists, why a key was selected, what deletion means historically, which queries justify an index, and how changed requirements alter the design.
+
+## 12. ORM-specific evidence
+
+When Entity Framework Core is present, distinguish:
+
+- LINQ/application expression;
+- translation preview such as `ToQueryString()` when appropriate;
+- actual executed `DbCommand` from supported logging/interception evidence;
+- generated migration SQL;
+- entity/change-tracking state versus physical SQL operations.
+
+Do not present a translation preview as proof of the exact command that executed.
+
+For other ORMs, apply the same principle using framework-supported evidence instead of guessing.
+
+## 13. Cross-lab navigation
+
+Database Lab owns database depth; System Lab owns end-to-end system context.
+
+When database exploration reaches service boundaries, request/event flow, traffic, availability, security, deployment, or system-wide failure behavior, offer `/system-lab` when installed.
+
+When `/system-lab` reaches a database node and the learner needs schema/query/index/ORM/plan depth, return to `/db-lab`.
+
+## 14. Delivery-completion visibility
+
+After successful delivery, Lean may visibly recommend `/db-lab` while the change is fresh when the accepted diff changed database-related evidence such as entities, migrations, schema, SQL/query code, repository/persistence behavior, indexes, constraints, or transaction logic.
+
+Prefer learner-facing wording such as:
+
+```text
+★ /db-lab changes WI-24
+  This work changed database structure or behavior.
+  Explore affected relationships, queries, indexes, constraints, and ORM behavior.
+```
+
+Do **not** say "rebuild the database diagram" or "refresh the model". Current evidence is part of invoking the lab.
+
+Best-effort disposable workbench generation after delivery is allowed only when a safe development/test database is already known. Do not guess a database path, create/apply migrations, or touch Production just to generate a learning artifact. Generation failure never changes delivery state.
+
+## 15. Tooling
+
+Optional IDE/database extensions may improve exploration but are not workflow authority and must not become a required dependency unless the project explicitly owns that requirement.
+
+Prefer provider/framework-native inspection plus repository evidence. The SQLite workbench is a reusable read-only learning aid; future provider/ORM adapters should preserve the same evidence, current-by-default behavior, and safety contract.

package/assets/generated/core/core/skills/deliver/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deliver
-description: "Streamlined delivery after implementation review/approval: short-lived branch recovery/setup, selective commit/push/PR/CI mechanics, one explicit merge/finalize gate, post-merge CI, and safe delivered-branch cleanup."
+description: "Streamlined delivery after implementation review/approval: short-lived branch recovery/setup, selective commit/push/PR/CI mechanics, one explicit merge/finalize gate, post-merge CI, safe delivered-branch cleanup, and optional non-blocking learning handoff."
 argument-hint: "[optional work-item ID or external key]"
 user-invocable: true
 disable-model-invocation: true
@@ -49,8 +49,11 @@ D. MERGE + FINALIZE DECISION — one human gate
 E. POST-MERGE DEFAULT-BRANCH CI — automatic observation
 F. DELIVERED-BRANCH FINALIZATION — automatic when authorized and safe
 G. DELIVERY COMPLETE
+H. OPTIONAL LEARNING HANDOFF — visible, read-only/non-blocking
 ```
 
+Phase H never changes whether engineering delivery is complete.
+
 ## 3. Resume-aware initial inspection
 
 Inspect only what is needed to determine the furthest safe delivery state, such as:
@@ -281,9 +284,9 @@ Never use force deletion merely to bypass uncertainty.
 
 If any safety condition fails, preserve the branch and report `BRANCH CLEANUP PENDING` with the exact reason instead of asking repetitive yes/no questions.
 
-## 11. Delivery completion
+## 11. Delivery completion and optional learning handoff
 
-Report the observed outcome:
+First report the observed engineering outcome:
 
 ```text
 DELIVERY COMPLETE
@@ -302,6 +305,73 @@ DELIVERY COMPLETE — BRANCH CLEANUP PENDING
 
 and preserve the branch.
 
+After engineering delivery is complete, use the accepted PR/work-item diff to classify optional learning relevance. This classification is read-only and does not create another delivery state.
+
+Database relevance can include observed changes to entities/models, migrations, DDL/schema, SQL/query/repository/persistence code, indexes/constraints, ORM mappings, or transaction/concurrency behavior.
+
+System-design relevance can include observed changes to APIs/contracts, service/module boundaries, cross-component dependencies, external integrations, messaging/events, caches, security/auth boundaries, observability, deployment/runtime topology, infrastructure, scaling/performance behavior, or failure handling.
+
+A changed file proves that evidence was touched; it does not by itself prove a physical-schema or runtime-behavior change. Use `changed`/`affected` wording conservatively and verify deeper claims through the corresponding lab.
+
+### Best-effort disposable workbench preparation
+
+After merge, satisfactory post-merge/default-branch evidence, and update to the delivered default-branch checkout, `/deliver` may prepare current disposable learning artifacts automatically when all prerequisites are already safe and unambiguous.
+
+System Lab:
+- when system-design relevance is present and `tools/lean-system-lab/system-workbench.py` exists, it may run the exporter against the current repository;
+- use a stable per-repository temp/cache output directory so an older disposable `workbench.json` can be compared before replacement;
+- pass the accepted changed-file list via `--changed-file` when practical;
+- never write generated workbench output into tracked project paths by default.
+
+Database Lab:
+- when database relevance is present, `tools/lean-db-lab/sqlite-workbench.py` exists, and a safe local development/test SQLite database path is already known from project setup/configuration/evidence, it may generate the current DB workbench;
+- do not guess a database path;
+- do not create a database, apply migrations, mutate data, inspect Production, or change code merely to prepare a learning artifact.
+
+For either lab:
+- artifact generation is read-only/best-effort;
+- failure/unavailability is reported briefly and never changes `DELIVERY COMPLETE`;
+- generation does not mean the human performed the learning activity or demonstrated understanding;
+- do not open browser/UI automatically unless normal repository/local-workflow conventions make that expected and non-disruptive.
+
+### Visible optional learning reminder
+
+Keep learning visible while the change is fresh. Prefer this order:
+
+```text
+OPTIONAL LEARNING — recommended while this change is fresh
+
+★ /db-lab changes <work-item>
+  This work changed database structure or behavior.
+  Explore affected relationships, queries, indexes, constraints, and ORM behavior.
+
+★ /system-lab changes <work-item>
+  This work changed system structure or runtime behavior.
+  Explore affected components, flows, dependencies, tradeoffs, and failure modes.
+
+○ /code-walkthrough <work-item>
+  Walk through the implementation and changed-file flow.
+
+○ /learning-review <work-item>
+  Test your understanding.
+
+Learning is optional and does not affect delivery state.
+```
+
+Only use `★` for a lab supported by the accepted change evidence. If a lab is not especially relevant, keep it visible as an available option when useful, for example:
+
+```text
+○ /db-lab
+  Explore the current database schema, relationships, queries, indexes, and ORM behavior.
+
+○ /system-lab
+  Explore the current architecture, runtime flows, dependencies, scaling, and failure behavior.
+```
+
+Do not tell the human to "rebuild", "refresh", or maintain a generated diagram. Invoking a lab means inspect current evidence and generate/show the current view.
+
+Do not turn these reminders into approval prompts. The human may invoke one, continue to deployment work, start another work item, or do nothing.
+
 ## 12. Deployment handoff
 
 If the delivered work item owns release/deployment engineering, successful engineering delivery may hand off to the selected environment's state-driven readiness workflow:
@@ -314,12 +384,14 @@ Readiness re-discovers current state and continues from the furthest safe point;
 
 The readiness workflow is environment-generic. Production remains an environment role with stronger policy; merge approval never implies remote or production-deployment authorization.
 
+The optional learning handoff does not block or replace deployment readiness when deployment is the sensible next engineering action.
+
 ## 13. Relationship to /start-work, /next-step, and /cleanup-branches
 
 `/start-work` establishes the short-lived work branch as routine implementation setup once implementation is actually authorized.
 
-`/next-step` answers `Where am I?`.
+`/next-step` answers `Where am I?` and may surface optional learning choices without creating learning-only workflow states.
 
-`/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision.
+`/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision. After successful engineering completion it may prepare disposable learning workbenches and shows an optional learning handoff without creating another gate.
 
 `/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -68,7 +68,7 @@ Use only states supported by observed evidence.
 
 Do not add a separate final-PR-acceptance state when the PR still exactly matches the already accepted local implementation. In that normal case, `/deliver` combines final acceptance and merge into the single `MERGE_READY` decision. If PR evidence changed materially, describe the required final PR review explicitly before returning to `MERGE_READY`.
 
-Do not add learning-only states such as `CODE_WALKTHROUGH_PENDING`. Optional coaching does not change engineering delivery state.
+Do not add learning-only states such as `CODE_WALKTHROUGH_PENDING`. Optional coaching and labs do not change engineering delivery state.
 
 ## 3. Output
 
@@ -96,9 +96,17 @@ When implementation is stable enough to learn from and the human appears interes
 /code-walkthrough <scope> — guided changed-file explanation [READ ONLY]
 /learning-review <scope> — understanding assessment [READ ONLY]
 /coach <topic> — focused concept coaching [READ ONLY]
+/db-lab [changes <work-item>] — current database/schema/query/ORM evidence [READ ONLY]
+/system-lab [changes <work-item>] — current architecture/runtime/failure/design evidence [READ ONLY]
 ```
 
-Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Do not recommend it as mandatory before `/deliver`.
+Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Prefer `/db-lab` when the question depends on concrete schema/query/index/ORM evidence. Prefer `/system-lab` when it depends on architecture, runtime flows, APIs, dependencies, failure behavior, scale, messaging, observability, security, deployment, testing, or system-design tradeoffs.
+
+When a known work-item diff materially touches one of those evidence areas, make the corresponding `changes <work-item>` option visibly relevant. Do not claim a runtime or physical-schema change solely because a file was touched.
+
+Labs inspect current evidence when invoked. Do not tell the human to refresh or rebuild a generated diagram.
+
+Do not recommend any learning activity as mandatory before `/deliver`.
 
 ## 5. Delivery handoff
 
@@ -140,7 +148,7 @@ Never merge from `/next-step` merely because CI is green.
 After merge:
 - if required default-branch CI is pending, return to `/deliver` to resume observation/finalization;
 - if failed, inspect/diagnose;
-- if green and branch finalization is safe/complete, report delivery complete.
+- if green and branch finalization is safe/complete, report delivery complete and optional relevant learning follow-ups without changing the delivery state.
 
 ## 6. Deployment handoff
 
@@ -173,3 +181,5 @@ Do not infer readiness of one environment from another. Production is never an i
 ## 7. Keep it lean
 
 Do not auto-run Reviewer, auto-run learning activities, auto-merge, auto-deploy, pin/select a model, or maintain duplicate workflow state outside Git/GitHub and the configured work-item/readiness authority.
+
+Generating a disposable read-only learning workbench is not the same as auto-running a learning activity or proving understanding. `/deliver` may prepare such artifacts best-effort after successful delivery when safe and relevant; learning itself remains optional.