@svashevchenko/ez-know 0.1.0

package/dist/reference/ez-know-extract-knowledge-from-code/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ez-know-extract-knowledge-from-code
+description: Extract AS-IS product knowledge from a codebase into the ez-know product-knowledge-base. Use when the user wants to start knowledge extraction from existing code.
+---
+
+# ez-know-extract-knowledge-from-code
+
+## Purpose
+
+Use this skill to extract AS-IS product knowledge from a codebase into the ez-know product knowledge base.
+
+The goal is product meaning, not a dependency map, ownership map, hotspot report, bus-factor report, or file catalog.
+
+## Core Principles
+
+- Work incrementally;
+- Keep the analysis scope small;
+- Inspect scope boundaries before finalizing conclusions;
+- Prefer evidence over assumptions;
+- Do not write large knowledge batches at once;
+- Maintain domain-oriented knowledge structure;
+- Every meaningful statement needs evidence.
+- Use questions when confidence is low or intent is unclear.
+- Treat conflicts as first-class objects instead of merging uncertain meanings.
+- Search existing records with `ez-know` MCP to avoid duplication and increase consistency.
+
+## Required ez-know MCP Resource Loading Pattern
+
+Before working with any object type, load the corresponding resources from MCP:
+
+1. object schema;
+2. extraction instruction for that object type.
+
+Perform analysis, candidate detection, ID drafting, duplicate checks, using the loaded MCP resources as references.
+Do not keep all resources in context by default. Load only what is needed for the current phase.
+
+If a required resource is unavailable:
+
+- do not invent its schema;
+- do not finalize objects of that type;
+- continue only with object types whose resources are available;
+- explicitly report the missing resource.
+
+## Patch Workflow
+
+Write extraction results through the knowledge patch workflow rather than by mutating canonical knowledge files directly.
+
+Recommended flow:
+
+1. Create or reuse a draft patch with `knowledge_patch`.
+2. Add ordered semantic operations for the extracted objects with `knowledge_patch`.
+3. Validate the patch with `knowledge_patch` and keep the returned validation fingerprint.
+4. Apply the patch with `knowledge_patch_apply` only after explicit approval and only with the latest validation fingerprint.
+5. Re-check the updated knowledge store after apply when the patch changes existing records or resolves conflicts.
+
+If validation fails, the fingerprint becomes stale, or approval is missing, stop and report the blocker rather than guessing or forcing the write.
+
+When creating or updating patch metadata, set `rootFolder` to the repository directory that is being analyzed for extraction.
+
+Before the validation step is treated as final, run a duplicate audit over all proposed `create` operations against the effective knowledge state and earlier pending patches.
+Patch validation is necessary but not sufficient because it protects against ID and reference issues more reliably than semantic duplication.
+
+## Stable ID Strategy
+
+Use this pattern for knowledge items ids:
+
+```text
+<object-type>.<domain-slug>.<object-slug>
+```
+
+Examples:
+
+```text
+domain.orders
+entity.orders.order
+rel.orders.order-has-items
+cap.orders.order-lifecycle
+feature.orders.cancel-order
+rule.orders.paid-orders-cannot-be-cancelled
+constraint.orders.erp-sync-one-way
+why.orders.refund-required-for-paid-order
+ev.orders.cancel-disabled-paid
+q.orders.paid-cancel-rationale
+conflict.orders.invoice-domain-boundary
+```
+
+Default convention:
+
+- domains: `domain.<domain-slug>`;
+- other objects: `<object-type>.<domain-slug>.<object-slug>`.
+
+## Domain-Based Storage Model
+
+Top-level grouping is always by domain.
+Each domain owns its folder, for example:
+
+```text
+ez-know/orders/
+ez-know/billing/
+ez-know/payments/
+```
+
+If an object belongs to multiple domains, store it in its owning domain and reference it from the others by stable ID.
+
+## Core Knowledge Hierarchy
+
+Always organize extracted knowledge as:
+
+```text
+Domain
+  -> Entity
+          -> Entity Relationship
+              -> Capability
+                  -> Feature
+                      -> Business Rule
+                      -> Constraint
+                          -> Rationale
+                                  -> Evidence
+                                      -> Question
+```
+
+This hierarchy is conceptual. JSON files can still be normalized by object type.
+
+## Duplicate Prevention
+
+Before creating any object:
+
+1. Search existing knowledge through `ez-know`.
+2. Reuse the existing ID when the meaning matches.
+3. Add aliases, evidence, relationships, rules, or confidence updates to the existing object instead of duplicating it.
+4. Create a conflict when evidence supports incompatible interpretations.
+5. Create a new object only when lookup does not find a matching record.
+
+Use the effective knowledge state as the duplicate-check base, not only canonical files.
+This means duplicate checks must consider:
+
+- canonical knowledge already loaded in the store;
+- earlier pending draft patches that are part of the effective read state;
+- other newly proposed objects in the current draft patch.
+
+Treat these as mandatory duplicate triggers that require comparison before any `create` is finalized:
+
+- same or near-identical name;
+- same core noun phrase in `business_definition`, `purpose`, or `description`;
+- same external system, runtime surface, or data store described from another scope;
+- same relationships, features, rules, or evidence cluster pointing at the same concept;
+- a domain-local object that appears to restate an existing cross-domain concept.
+
+When a duplicate trigger fires:
+
+1. Query matching records through `ez-know` MCP.
+2. Compare purpose, evidence, connected objects, and scope.
+3. Resolve the candidate in exactly one way:
+   - reuse the existing object and switch to `update`;
+   - keep `create` because the concept is genuinely distinct;
+   - create a conflict;
+   - stop and report unresolved duplicate risk.
+
+Do not justify a new object only by ID uniqueness or successful patch validation.
+
+## Evidence-First Rule
+
+Every meaningful statement must reference evidence.
+
+Evidence can come from code, type/interface names, API paths, route names, tests, UI text, translation strings, validation schemas, comments, documentation, repository search results, or human confirmation.
+
+Evidence means: this source supports this product statement.
+
+## Scope Boundary Discovery
+
+After selecting a narrow scope, inspect the first-order references that leave it before finalizing extracted objects.
+
+Look for:
+
+- imports or exports that target files outside the selected area;
+- referenced URLs, routes, commands, schemas, generated clients, or configuration inputs;
+- entrypoints, adapters, registries, or wiring code that connect the scope to another subsystem / module;
+- tests or documentation that describe interactions beyond the current area.
+
+Boundary discovery is not a request to build a dependency map.
+Its purpose is to confirm or reject cross-scope relationships that affect product meaning, externally visible behavior, access paths, data flow, or operational constraints.
+
+Do not continue traversing the whole repository by default.
+Inspect only the immediate external targets needed to understand the boundary.
+
+During boundary discovery, explicitly enumerate the first-order runtime data providers and sinks for each user-visible entity or feature in scope.
+This includes direct API reads, route-backed queries, store reads, emitted commands, and other immediate delivery paths required for the visible behavior to work.
+
+Do not turn that enumeration into a full dependency graph.
+Use it only to decide whether a cross-scope relationship, constraint, or question is required.
+
+## Cross-Scope Evidence Rule
+
+If files in the selected scope clearly reference another subsystem, inspect that counterpart before finalizing relationships, capabilities, features, rules, or constraints that may depend on it.
+
+Use the counterpart inspection to answer questions such as:
+
+- Is the external reference part of how a user-visible capability is delivered or accessed?
+- Does it establish a real interaction, ownership, dependency, or data flow between product-relevant objects?
+- Does it impose a constraint or explain why a visible behavior exists?
+- Is the object still able to perform its main runtime behavior if that external subsystem is absent?
+
+Do not promote raw implementation dependencies into knowledge objects unless they support a product-relevant statement with evidence.
+
+If a user-visible entity or feature cannot perform its main runtime behavior without an external subsystem, create a cross-scope relationship unless direct evidence shows that the dependency belongs only to a narrower sub-object.
+
+Prefer:
+
+- `depends_on` when the source object requires the target for runtime delivery of its visible behavior;
+- `references` when the source object can point to, display, or project the target without requiring it to function.
+
+If the counterpart cannot be inspected within the current scope budget, lower confidence and create a question instead of silently omitting the possible link.
+
+## Certainty And Confidence
+
+Every object must include certainty and confidence.
+
+Use certainty:
+
+- `confirmed` - explicitly confirmed by human or authoritative documentation
+- `direct_evidence` - directly supported by code/tests/UI/docs
+- `inferred` - inferred from multiple signals
+- `weak_inference` - plausible but uncertain
+- `unknown` - captured as question only
+
+Use confidence:
+
+- `0.90-1.00` confirmed or explicit direct evidence
+- `0.70-0.89` strong direct evidence
+- `0.50-0.69` plausible inference
+- `0.00-0.49` weak inference, requires human clarification
+
+If confidence is below `0.70`, generate a question.
+
+## Required Agent Behavior
+
+Use cautious language in all generated fields.
+
+Prefer:
+
+- appears to
+- suggests
+- likely exists because
+- is inferred from
+
+Avoid:
+
+- was designed to
+- business requires
+- the intended behavior is
+
+unless confirmed.
+
+## Your extraction workflow tasks:
+
+Analyze each selected area in this order:
+
+1. **Scope selection**  
+   Select a narrow code or documentation area. Avoid whole-project analysis unless the user explicitly requests it.
+
+2. **Boundary discovery**  
+   Inspect first-order references that leave the selected area. Use them to identify the minimum adjacent context required to understand externally visible behavior.
+
+3. **Domain detection**  
+   Identify the likely business domain or bounded context.
+
+4. **Entity extraction**  
+   Extract core business objects, actors, aggregate-like concepts, external systems, and persistent domain nouns.
+
+5. **Duplicate audit**  
+   Compare every proposed `create` against the effective knowledge state, earlier pending patches, and other proposed objects in the current patch. Resolve each candidate by reuse, update, distinct-create, conflict, or explicit stop.
+
+6. **Relationship extraction**  
+   Connect known entities before deriving higher-level behavior. Capture ownership, dependency, lifecycle, data flow, and interaction relationships.
+
+7. **Feature extraction**  
+   Identify user-visible or system-visible features that implement capabilities.
+
+8. **Capability extraction**  
+   Identify business abilities supported by the area. Capabilities should be based on entities, relationships, and features.
+
+9. **Rule and constraint extraction**  
+   Extract business rules, validations, invariants, limits, permissions, and process constraints.
+
+10. **Rationale extraction**  
+   Capture rationale only when there is evidence. Do not speculate about intent.
+
+11. **Question and conflict extraction**  
+   Record unresolved questions, ambiguities, contradictions, and weak assumptions.
+
+Capabilities or features may be noted earlier as candidates, but they should be finalized only after the relevant entities and relationships are understood.
+
+## Self-Validation Before Final Output
+
+Before returning a final knowledge output, check:
+
+- required MCP schema and instruction resources were loaded for each object type;
+- every object has evidence or is clearly marked as a question/hypothesis;
+- obvious first-order references leaving the scope were checked or explicitly deferred;
+- every user-visible entity and feature has its external runtime data providers accounted for as relationships, constraints, or explicit open questions;
+- object IDs follow the current ID convention;
+- relationships point to known or proposed objects;
+- each proposed `create` was compared against semantically similar records in the effective knowledge state;
+- earlier pending draft patches were included in duplicate checks;
+- same-name or same-purpose records in other domains were explicitly reviewed before finalizing creates;
+- every possible duplicate was resolved by reuse, update, conflict, distinct-create justification, or explicit stop;
+- uncertain claims are not written as facts;
+
+## Completion Criteria
+
+The extraction is complete when:
+
+- entities are extracted with business definitions, aliases, and terminology notes;
+- entity relationships are extracted;
+- features are extracted as atomic business functions;
+- capabilities group related features where grouping is useful;
+- business rules are captured as observable behavior and product rules;
+- constraints are captured with type, cause, impact, workaround/removability where known;
+- rationales are captured where possible;
+- every major statement has evidence;
+- every important uncertain point has a question;
+- confidence and certainty are present everywhere;
+- every `create` operation was checked against the effective knowledge state through `ez-know`;
+- cross-patch duplicates were resolved before the task was treated as complete;
+- no new object remained justified only by unique ID or patch validation success;
+- extraction changes were written through the patch workflow and not by direct canonical file edits;
+- updates are written into domain-oriented JSON files under `ez-know/<domain-slug>/`.
+
+## Stop Conditions
+
+Stop expanding the analysis when:
+
+- the scope becomes too broad;
+- required MCP resources are missing;
+- evidence is insufficient;
+- duplication risk is high;
+- the model would need to guess business intent.
+
+When stopped, return a partial result and a clear list of what remains unresolved.

package/dist/reference/ez-know-update-knowledge-base/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: ez-know-update-knowledge-base
+description: Analyze staged changes, a commit, or a commit range and propose validated ez-know draft patches that update the knowledge model from those code changes. Use when the user wants knowledge maintenance driven by git diffs rather than full codebase extraction.
+---
+
+# update-knowledge-from-git
+
+## Purpose
+
+Use this skill to maintain the ez-know product knowledge base from an increment of code change.
+
+The increment may be:
+
+- staged changes;
+- a single commit;
+- a commit range.
+
+The goal is to update product knowledge affected by the increment, not to restate the whole domain model.
+
+## Core Principles
+
+- Work from the git increment as the source boundary.
+- Prefer small, coherent knowledge updates over broad speculative rewrites.
+- Inspect changed scope boundaries before finalizing semantic updates.
+- Use commit messages as hints only, never as authoritative facts.
+- Prefer evidence from diffs, tests, routes, schemas, docs, and UI text.
+- Ignore pure churn when it does not change product meaning.
+- Reuse and update existing knowledge whenever possible.
+- Create validated draft patches immediately.
+- Do not apply patches without explicit approval.
+
+## Supported Inputs
+
+Support these modes:
+
+- `staged` - analyze staged changes only;
+- `commit <sha>` - analyze a single commit;
+- `range <from>..<to>` - analyze a commit range.
+
+For commit and range modes, commit messages may help explain likely intent, but all final knowledge updates must be justified by the actual diff and related evidence.
+
+## Required ez-know MCP Resource Loading Pattern
+
+Before working with any object type, load the corresponding resources from MCP:
+
+1. object schema;
+2. extraction instruction for that object type.
+
+Load only the resources needed for the current batch and current stage.
+
+If a required resource is unavailable:
+
+- do not invent its schema;
+- do not finalize objects of that type;
+- continue only with object types whose resources are available;
+- explicitly report the missing resource.
+
+## Patch Workflow
+
+Write results through the knowledge patch workflow rather than by mutating canonical knowledge files directly.
+
+Required flow:
+
+1. Create draft patch records immediately for the detected semantic batches.
+2. Add ordered semantic operations with `knowledge_patch`.
+3. Validate each draft patch with `knowledge_patch`.
+4. Keep each returned validation fingerprint.
+5. Apply patches with `knowledge_patch_apply` only after explicit approval and only with the latest validation fingerprint.
+
+If validation fails, keep the draft patch, report the diagnostics, and stop short of apply.
+
+## Evidence Rules
+
+Every meaningful statement must reference evidence.
+
+Preferred evidence sources for this skill:
+
+- `git_diff` for changed behavior, removed behavior, renamed behavior, and modified constraints;
+- `increment_description` for commit subject/body hints;
+- `code`, `test`, `api`, `route`, `schema`, `documentation`, `ui_text`, or `comment` when the diff points to them.
+
+Evidence rules:
+
+- keep excerpts short;
+- do not store large code blocks;
+- use commit messages only as secondary support;
+- when the diff is ambiguous, capture a question or conflict instead of asserting intent.
+
+## Changed Scope Boundary Discovery
+
+After identifying the changed files in a batch, inspect the first-order references that leave the changed area before finalizing semantic updates.
+
+Look for:
+
+- changed imports or exports that target files outside the diff cluster;
+- referenced URLs, routes, commands, schemas, generated clients, or configuration inputs;
+- entrypoints, adapters, registries, or wiring code that connect the changed area to another subsystem;
+- tests or documentation touched by the increment that clarify interactions beyond the edited files.
+
+Boundary discovery is not a request to reconstruct the full architecture.
+Its purpose is to confirm or reject cross-scope relationships, access paths, data flow, externally visible behavior, or operational constraints that are affected by the increment.
+
+Do not expand arbitrarily through the repository.
+Inspect only the immediate external targets needed to understand the changed boundary.
+
+## Cross-Scope Update Rule
+
+If the increment clearly references another subsystem, inspect that counterpart before finalizing updates to relationships, capabilities, features, rules, constraints, rationales, or deletes that may depend on it.
+
+Use the counterpart inspection to answer questions such as:
+
+- Does the change alter how a user-visible capability is delivered or accessed?
+- Does it establish, remove, or modify a real interaction, ownership, dependency, or data flow between product-relevant objects?
+- Does it add, remove, or clarify a constraint that is only visible when the adjacent subsystem is checked?
+
+Do not promote raw implementation dependencies into knowledge objects unless they support a product-relevant statement with evidence.
+
+If the counterpart cannot be inspected within the current batch budget, lower confidence and create a question or conflict instead of silently omitting the possible link or asserting a delete.
+
+## Stable ID Strategy
+
+Use this pattern for knowledge item ids:
+
+```text
+<object-type>.<domain-slug>.<object-slug>
+```
+
+Examples:
+
+```text
+domain.orders
+entity.orders.order
+rel.orders.order-has-items
+cap.orders.order-lifecycle
+feature.orders.cancel-order
+rule.orders.paid-orders-cannot-be-cancelled
+constraint.orders.erp-sync-one-way
+why.orders.refund-required-for-paid-order
+ev.orders.orders-diff-cancel-flow
+q.orders.cancel-flow-removal-meaning
+conflict.orders.checkout-removal-interpretation
+```
+
+## Automatic Batching
+
+If the increment is too large or semantically mixed for reliable single-pass reasoning, decompose it automatically before drafting operations.
+
+Batching priority:
+
+1. semantic coherence;
+2. domain coherence;
+3. file clustering;
+4. commit clustering.
+
+Examples of separate batches:
+
+- orders lifecycle behavior updates;
+- billing rule changes;
+- explicit removals;
+- ambiguous changes that should become questions or conflicts.
+
+Do not ask the user to approve the batching plan before creating draft patches. The skill must proceed automatically.
+
+## Large Increment Strategy
+
+For large staged diffs or ranges, use a two-phase workflow:
+
+1. inventory the whole increment;
+2. classify likely semantic changes, likely non-semantic churn, and ambiguous areas;
+3. create semantic batches;
+4. process each batch independently;
+5. validate each draft patch independently;
+6. return one patch or many depending on coherence.
+
+Never require the model to reason over the entire raw diff in one pass when safe batching is possible.
+
+## Update Policy
+
+Before creating any object:
+
+1. search existing knowledge through `ez-know`;
+2. reuse the existing id when the meaning matches;
+3. update existing records when the increment modifies known behavior;
+4. create a new object only when the meaning is genuinely new;
+5. create a conflict when evidence supports incompatible interpretations.
+
+Prefer `update` over `create` when the change appears to refine or replace an existing concept.
+
+Use the effective knowledge state as the duplicate-check base, not only canonical files.
+This means duplicate checks must consider:
+
+- canonical knowledge already loaded in the store;
+- earlier pending draft patches that are part of the effective read state;
+- other newly proposed objects in the current draft patch or draft patch batch.
+
+Treat these as mandatory duplicate triggers that require comparison before any `create` is finalized:
+
+- same or near-identical name;
+- same core noun phrase in `business_definition`, `purpose`, `description`, or `statement`;
+- same external system, runtime surface, or data store described from another changed scope;
+- same relationships, features, rules, or evidence cluster pointing at the same concept;
+- a domain-local object that appears to restate an existing cross-domain concept.
+
+When a duplicate trigger fires:
+
+1. query matching records through `ez-know` MCP;
+2. compare purpose, evidence, connected objects, and changed scope;
+3. resolve the candidate in exactly one way:
+   - reuse the existing object and switch to `update`;
+   - keep `create` because the concept is genuinely distinct;
+   - create a conflict;
+   - stop and report unresolved duplicate risk.
+
+Do not justify a new object only by ID uniqueness or successful patch validation.
+
+## Delete Policy
+
+Delete operations are allowed, but use a stricter threshold than create or update.
+
+Use replacement-first delete handling:
+
+- if knowledge was renamed, narrowed, reframed, or moved, prefer `update` or create-and-relink;
+- emit `delete` only when the diff clearly removes the product meaning itself;
+- if removal is plausible but uncertain, do not delete;
+- instead create a question, conflict, or lower-confidence update.
+
+When removals and clean updates are mixed, prefer separate draft patches so deletes do not contaminate unrelated updates.
+
+## Extraction Focus
+
+Analyze each batch in this order:
+
+1. scope the affected domain or semantic area;
+2. inspect first-order references that leave the changed area;
+3. identify changed or newly relevant entities;
+4. run a duplicate audit over every proposed `create` against the effective knowledge state, earlier pending patches, and other proposed objects in the batch;
+5. identify changed relationships;
+6. identify changed features;
+7. identify changed capabilities;
+8. identify changed rules and constraints;
+9. identify supported rationales when evidence exists;
+10. identify questions and conflicts for unresolved meaning;
+11. decide whether any explicit deletes are justified.
+
+Do not re-extract unaffected parts of the domain just because they are nearby in code.
+
+## Certainty And Confidence
+
+Every object must include certainty and confidence.
+
+Use certainty:
+
+- `confirmed` - explicitly confirmed by human or authoritative documentation
+- `direct_evidence` - directly supported by diff, code, tests, UI, or docs
+- `inferred` - inferred from multiple signals in the increment
+- `weak_inference` - plausible but uncertain
+- `unknown` - captured as question only
+
+Use confidence:
+
+- `0.90-1.00` explicit and strong direct evidence
+- `0.70-0.89` strong direct evidence with limited ambiguity
+- `0.50-0.69` plausible inference
+- `0.00-0.49` weak inference, requires clarification
+
+If confidence is below `0.70`, generate a question.
+
+## Stop Conditions
+
+Stop expanding a batch when:
+
+- evidence is insufficient;
+- the increment becomes too ambiguous;
+- required MCP resources are missing;
+- duplicate risk is high;
+- the model would need to guess product intent.
+
+When stopped:
+
+- keep the draft patch if useful;
+- report unresolved areas clearly;
+- prefer partial validated output over speculative completion.
+
+## Completion Criteria
+
+The skill is complete when:
+
+- the input increment was analyzed from `staged`, `commit`, or `range`;
+- semantic batches were created automatically when needed;
+- one or more draft patches were created immediately;
+- each draft patch contains only semantically coherent operations;
+- each patch was validated independently;
+- obvious first-order references leaving the changed area were checked or explicitly deferred;
+- diffs that carry no product meaning were skipped or reported as churn;
+- deletes were emitted only when removal was clear;
+- ambiguous changes became questions or conflicts instead of unsupported facts;
+- every `create` operation was checked against the effective knowledge state through `ez-know`;
+- cross-patch duplicates were resolved before any batch was treated as complete;
+- no new object remained justified only by unique ID or patch validation success;
+- no patch was applied without explicit approval.
+
+## Expected Output
+
+Return a compact summary containing:
+
+- source analyzed;
+- commits and files reviewed when relevant;
+- detected batches;
+- created draft patch ids;
+- scope of each patch;
+- validation result of each patch;
+- unresolved ambiguities, skipped churn, and delete rationale where relevant.