@pigcloud/skills 1.0.3 → 1.0.5

package/skills/references/business-fact-extraction.md

@@ -0,0 +1,414 @@
+# Business Fact Extraction
+
+## Goal
+
+Turn code-backed evidence into a three-stage artifact:
+
+1. code facts
+2. business facts
+3. CodeWiki updates
+
+## Evidence Order
+
+Use the strongest source available first:
+
+1. runtime behavior
+2. automated tests
+3. code paths
+4. schema and contracts
+5. docs and runbooks
+6. comments and naming
+
+## Fact Types
+
+- evidence-backed fact: directly supported by code or tests
+- inferred business fact: a reasonable business meaning derived from evidence
+- unknown: the code does not prove it yet
+- contradiction: two sources disagree
+
+## Output Shape
+
+### 1. Code Facts
+
+#### `knowledge-base/realtime-code/modules.md`
+
+- module:
+- current responsibility:
+- key entry points:
+- important constraints:
+- last verified:
+
+#### `knowledge-base/realtime-code/flows.md`
+
+- flow name:
+- trigger:
+- path:
+- output:
+- failure points:
+- notes:
+
+#### `knowledge-base/realtime-code/runtime-notes.md`
+
+- fact:
+- evidence:
+- affected area:
+- date:
+- notes:
+
+### 2. Business Facts
+
+#### `knowledge-base/requirements/decisions.md`
+
+- decision:
+- reason:
+- date or context:
+- affected artifact:
+- notes:
+
+#### `knowledge-base/requirements/acceptance.md`
+
+- requirement:
+- acceptance criteria:
+- out of scope:
+- open questions:
+- confirmed by:
+
+#### `knowledge-base/requirements/conflicts.md`
+
+- conflict:
+- source:
+- impact:
+- resolution:
+- status:
+
+### 3. CodeWiki Update
+
+#### `knowledge-base/codewiki/overview.md`
+
+- one-line summary:
+- what the system does:
+- what changed:
+- why it matters:
+
+#### `knowledge-base/codewiki/architecture.md`
+
+- layers:
+- boundaries:
+- dependencies:
+- major integration points:
+
+#### `knowledge-base/codewiki/modules.md`
+
+- module name:
+- responsibility:
+- main interfaces:
+- related runtime facts:
+
+#### `knowledge-base/codewiki/flows.md`
+
+- request flow:
+- data flow:
+- error flow:
+- handoff flow:
+
+#### `knowledge-base/codewiki/api.md`
+
+- endpoint or contract:
+- request shape:
+- response shape:
+- constraints:
+
+#### `knowledge-base/codewiki/runbook.md`
+
+- startup:
+- verify:
+- troubleshoot:
+- recover:
+
+#### `knowledge-base/codewiki/conventions.md`
+
+- naming:
+- layering:
+- error handling:
+- logging:
+- data handling:
+
+### 4. Enterprise Note
+
+#### `knowledge-base/enterprise/decisions.md`
+
+- decision:
+- reason:
+- scope:
+- date:
+- reusable lesson:
+
+#### `knowledge-base/enterprise/pitfalls.md`
+
+- pitfall:
+- context:
+- why it failed:
+- how to avoid it:
+
+#### `knowledge-base/enterprise/examples.md`
+
+- example:
+- context:
+- lesson:
+- reusable pattern:
+
+#### `knowledge-base/enterprise/ai-coding-rules.md`
+
+- rule:
+- when it applies:
+- why it matters:
+- examples:
+
+## Writing Rules
+
+- Keep one fact per line.
+- Point each fact back to evidence.
+- Separate observed behavior from interpretation.
+- Mark uncertainty explicitly.
+- Do not mix solution ideas into the fact list.
+- Write the three stages in order and keep them visually separate.
+- Update the smallest matching file in each target layer.
+- Keep file targets and file content in the same order.
+
+## Auto-Write Pack
+
+Use `skills/extract-business-facts/scripts/write-knowledge-base.js` when the staged readout should be written into the knowledge base.
+
+### Input Shape
+
+```json
+{
+  "files": {
+    "knowledge-base/realtime-code/modules.md": [
+      {
+        "module": "order-service",
+        "current responsibility": "creates orders and reserves inventory",
+        "key entry points": "createOrder(), reserveInventory()",
+        "important constraints": "stock must be checked before commit",
+        "last verified": "2026-06-22"
+      }
+    ]
+  }
+}
+```
+
+### Command
+
+```bash
+node skills/extract-business-facts/scripts/write-knowledge-base.js --input fact-pack.json
+```
+
+### Behavior
+
+- Writes only under `knowledge-base/`
+- Keeps the file-specific field order
+- Replaces the generated block between markers when it already exists
+- Preserves the surrounding manual notes
+- Supports `--dry-run` for preview and `--sample` for a sample pack
+
+## Handoff Targets
+
+- `domain-modeling` when the facts need boundary or concept normalization
+- `spec` when the facts need to become a user-confirmable spec
+- `knowledge-capture` when the facts are stable and ready to persist
+
+## Sample Readout
+
+- code facts: module behavior, entry points, constraints, runtime evidence
+- business facts: decisions, acceptance criteria, conflicts, open questions
+- CodeWiki update: flow, architecture, module, API, runbook, convention deltas
+- enterprise note: pitfalls, examples, reusable rules
+
+## Full Example
+
+### Code Facts
+
+#### `knowledge-base/realtime-code/modules.md`
+
+- module: `order-service`
+- current responsibility: creates orders and reserves inventory
+- key entry points: `createOrder()`, `reserveInventory()`
+- important constraints: stock must be checked before commit
+- last verified: 2026-06-22
+
+#### `knowledge-base/realtime-code/flows.md`
+
+- flow name: checkout order placement
+- trigger: user confirms checkout
+- path: validate stock -> reserve inventory -> create order
+- output: confirmed order or shortage error
+- failure points: stock shortage, reservation failure
+- notes: reservation must happen before the order commit
+
+### Business Facts
+
+#### `knowledge-base/requirements/decisions.md`
+
+- decision: inventory must be reserved before order confirmation
+- reason: avoid overselling
+- date or context: 2026-06-22, order flow review
+- affected artifact: checkout spec
+- notes: failure should return a clear stock shortage message
+
+#### `knowledge-base/requirements/acceptance.md`
+
+- requirement: checkout must not confirm an order when stock is unavailable
+- acceptance criteria: shortage blocks confirmation and returns a clear message
+- out of scope: backorder design
+- open questions: whether to retry reservation automatically
+- confirmed by: order flow review
+
+### CodeWiki Update
+
+#### `knowledge-base/codewiki/flows.md`
+
+- request flow: checkout -> validate stock -> reserve inventory -> create order
+- data flow: cart snapshot -> reservation record -> order record
+- error flow: stock shortage -> stop checkout -> return shortage reason
+- handoff flow: checkout service hands off to inventory service and order repository
+
+#### `knowledge-base/codewiki/modules.md`
+
+- module name: `order-service`
+- responsibility: coordinates checkout and order creation
+- main interfaces: `createOrder()`, `reserveInventory()`
+- related runtime facts: inventory must be reserved before commit
+
+### Enterprise Note
+
+#### `knowledge-base/enterprise/pitfalls.md`
+
+- pitfall: reservation happens after order creation
+- context: checkout path
+- why it failed: allowed overselling under concurrent requests
+- how to avoid it: reserve before committing the order
+
+## End-to-End Example
+
+### 1. Source Input
+
+- PRD / spec note: checkout must not confirm when stock is insufficient
+- code evidence: `order-service` reserves inventory before creating the order
+- runtime evidence: shortage returns a stock error before commit
+
+### 2. Extracted Output
+
+- code facts:
+  - `knowledge-base/realtime-code/modules.md`: `order-service` coordinates checkout and inventory reservation
+  - `knowledge-base/realtime-code/flows.md`: checkout -> validate stock -> reserve inventory -> create order
+- business facts:
+  - `knowledge-base/requirements/decisions.md`: reserve inventory before order confirmation
+  - `knowledge-base/requirements/acceptance.md`: shortage blocks confirmation and returns a clear message
+- CodeWiki update:
+  - `knowledge-base/codewiki/flows.md`: document request / data / error / handoff flow
+  - `knowledge-base/codewiki/modules.md`: document `order-service` responsibilities and interfaces
+- enterprise note:
+  - `knowledge-base/enterprise/pitfalls.md`: reservation after order creation causes overselling
+  - `knowledge-base/enterprise/ai-coding-rules.md`: reserve before commit under concurrency
+
+### 3. Fact Pack
+
+```json
+{
+  "files": {
+    "knowledge-base/realtime-code/modules.md": [
+      {
+        "module": "order-service",
+        "current responsibility": "coordinates checkout and inventory reservation",
+        "key entry points": "createOrder(), reserveInventory()",
+        "important constraints": "stock must be checked before commit",
+        "last verified": "2026-06-22"
+      }
+    ],
+    "knowledge-base/requirements/decisions.md": [
+      {
+        "decision": "inventory must be reserved before order confirmation",
+        "reason": "avoid overselling",
+        "date or context": "2026-06-22, checkout review",
+        "affected artifact": "checkout spec",
+        "notes": "shortage returns a clear error"
+      }
+    ],
+    "knowledge-base/codewiki/flows.md": [
+      {
+        "request flow": "checkout -> validate stock -> reserve inventory -> create order",
+        "data flow": "cart snapshot -> reservation record -> order record",
+        "error flow": "stock shortage -> stop checkout -> return shortage reason",
+        "handoff flow": "checkout service hands off to inventory service and order repository"
+      }
+    ],
+    "knowledge-base/enterprise/pitfalls.md": [
+      {
+        "pitfall": "reservation happens after order creation",
+        "context": "checkout path",
+        "why it failed": "allowed overselling under concurrent requests",
+        "how to avoid it": "reserve before committing the order"
+      }
+    ]
+  }
+}
+```
+
+### 4. Persist
+
+```bash
+node skills/extract-business-facts/scripts/write-knowledge-base.js --input fact-pack.json
+```
+
+### 5. `knowledge-capture`
+
+- Normalize the extracted note.
+- Link it back to the originating skill.
+- Persist the fact pack only when the note is ready.
+
+#### `knowledge-base/enterprise/ai-coding-rules.md`
+
+- rule: reserve inventory before committing the order
+- when it applies: any checkout flow that can oversell
+- why it matters: keeps business state consistent under concurrency
+- examples: validate stock, reserve, then create the order
+
+## Sample Output
+
+### Code Facts
+
+#### `knowledge-base/realtime-code/modules.md`
+
+- module: `order-service`
+- current responsibility: creates orders and reserves inventory
+- key entry points: `createOrder()`, `reserveInventory()`
+- important constraints: stock must be checked before commit
+- last verified: 2026-06-22
+
+### Business Facts
+
+#### `knowledge-base/requirements/decisions.md`
+
+- decision: inventory must be reserved before order confirmation
+- reason: avoid overselling
+- date or context: 2026-06-22, order flow review
+- affected artifact: checkout spec
+- notes: failure should return a clear stock shortage message
+
+### CodeWiki Update
+
+#### `knowledge-base/codewiki/flows.md`
+
+- request flow: checkout -> validate stock -> reserve inventory -> create order
+- data flow: cart snapshot -> reservation record -> order record
+- error flow: stock shortage -> stop checkout -> return shortage reason
+- handoff flow: checkout service hands off to inventory service and order repository
+
+### Enterprise Note
+
+#### `knowledge-base/enterprise/pitfalls.md`
+
+- pitfall: reservation happens after order creation
+- context: checkout path
+- why it failed: allowed overselling under concurrent requests
+- how to avoid it: reserve before committing the order

package/skills/references/golden-prompt-suite.js

@@ -16,7 +16,7 @@ const cases = [
     'We have a new request but I am not sure which stage should handle it.',
     ['next skill', 'stage decision', 'handoff note'],
     'Do not perform the target skill\'s work.',
-    'product-intake',
+    'spec',
   ),
   makeCase(
     'workflow-router',
@@ -24,7 +24,7 @@ const cases = [
     'The brief is ready. Which stage should receive it next?',
     ['next skill', 'stage decision', 'handoff note'],
     'Do not perform the target skill\'s work.',
-    'spec-refinement',
+    'spec',
   ),
   makeCase(
     'workflow-router',
@@ -36,32 +36,57 @@ const cases = [
   ),
 
   makeCase(
-    'product-intake',
+    'spec',
     'product-reminder-feature',
     'We need a reminder feature for inactive users.',
     ['product brief', 'scope', 'acceptance outline', 'open questions'],
     'Do not jump into design or code.',
-    'spec-refinement',
+    'spec',
   ),
   makeCase(
-    'product-intake',
+    'spec',
     'product-retention-gap',
     'Users keep missing renewal emails; help me define the product scope.',
     ['product objective', 'scope', 'acceptance outline', 'open questions'],
     'Do not decide implementation details.',
-    'spec-refinement',
+    'spec',
   ),
   makeCase(
-    'product-intake',
+    'spec',
     'product-unclear-opportunity',
     'We think there is a retention problem, but the exact feature is unclear.',
     ['product objective', 'scope', 'acceptance outline', 'open questions'],
     'Do not write technical design.',
-    'spec-refinement',
+    'spec',
   ),
 
   makeCase(
-    'spec-refinement',
+    'spec',
+    'spec-approved-brief',
+    'The brief is approved; turn it into an executable spec and task breakdown.',
+    ['executable spec', 'task breakdown plan', 'acceptance criteria', 'confirmation package'],
+    'Do not generate code or reopen discovery.',
+    'feature-build',
+  ),
+  makeCase(
+    'spec',
+    'spec-code-alignment',
+    'Compare the PRD with current project facts and implementation evidence, then produce the engineering spec.',
+    ['execution direction plan', 'impact scope', 'implementation inputs', 'conflict map'],
+    'Do not jump into implementation.',
+    'technical-design',
+  ),
+  makeCase(
+    'spec',
+    'spec-confirmation-pack',
+    'I need a confirmation package with the spec, tasks, and acceptance criteria before coding.',
+    ['executable spec', 'task breakdown plan', 'confirmation package'],
+    'Do not write code.',
+    'feature-build',
+  ),
+
+  makeCase(
+    'spec',
     'spec-approved-brief',
     'The brief is approved; turn it into an executable spec.',
     ['executable spec', 'acceptance criteria', 'impact scope', 'implementation inputs'],
@@ -69,7 +94,7 @@ const cases = [
     'feature-build',
   ),
   makeCase(
-    'spec-refinement',
+    'spec',
     'spec-code-gap',
     'Compare the PRD with the current code and identify gaps.',
     ['executable spec', 'impact scope', 'implementation inputs'],
@@ -77,7 +102,7 @@ const cases = [
     'feature-build',
   ),
   makeCase(
-    'spec-refinement',
+    'spec',
     'spec-align-with-code',
     'The requirement is messy; align it with existing behavior and make it engineer-ready.',
     ['executable spec', 'acceptance criteria', 'implementation input summary'],
@@ -257,7 +282,32 @@ const cases = [
     'Extract ubiquitous language from the current product notes.',
     ['domain map', 'core concepts', 'boundary notes'],
     'Do not write implementation code.',
-    'spec-refinement',
+    'spec',
+  ),
+
+  makeCase(
+    'extract-business-facts',
+    'extract-business-facts-from-code',
+    'Extract the business facts expressed by this order-processing code and explain the current behavior.',
+    ['code fact map', 'business fact map', 'codewiki delta'],
+    'Do not design a new solution.',
+    'knowledge-capture',
+  ),
+  makeCase(
+    'extract-business-facts',
+    'extract-business-invariants',
+    'From these service methods and tests, identify the business invariants and open questions.',
+    ['code fact map', 'business fact map', 'codewiki delta'],
+    'Do not rewrite the PRD.',
+    'domain-modeling',
+  ),
+  makeCase(
+    'extract-business-facts',
+    'extract-code-backed-terms',
+    'Turn this controller, service, and database flow into a terminology map with evidence.',
+    ['code fact map', 'business fact map', 'codewiki delta'],
+    'Do not generate code.',
+    'spec',
   ),
 
   makeCase(
@@ -332,7 +382,7 @@ const cases = [
     'Bootstrap a fresh repository scaffold and hand it off.',
     ['starter structure', 'installed bundle', 'setup notes'],
     'Do not start feature implementation.',
-    'product-intake',
+    'spec',
   ),
 
   makeCase(
@@ -361,7 +411,7 @@ const cases = [
   ),
 
   makeCase(
-    'spec-refinement',
+    'spec',
     'negative-direct-code',
     'Just code it, the PRD is small.',
     ['executable spec'],

package/skills/references/rule-loading-map.md

@@ -1,18 +1,18 @@
-# Rule Loading Map
-
-## Goal
-
-Keep rule loading separate from skill routing. Load the smallest rule set that matches the current task, then add the stack-specific overlay only when needed. When changed files are available, prefer them over workspace-wide heuristics.
-
-## Governance Context
-
-- `workflow-router` decides the next stage.
-- `skills/` decides the reusable execution pattern.
-- `rules/` decides the project constraints and must/never checks.
-- `CI / Test / Evidence` decides whether the result can be accepted.
-- For the higher-level explanation, see [docs/agent-governance-overview.md](../../docs/agent-governance-overview.md).
-
-## Load Order
+# Rule Loading Map
+
+## Goal
+
+Keep rule loading separate from skill routing. Load the smallest rule set that matches the current task, then add the stack-specific overlay only when needed. When changed files are available, prefer them over workspace-wide heuristics.
+
+## Governance Context
+
+- `workflow-router` decides the next stage.
+- `skills/` decides the reusable execution pattern.
+- `rules/` decides the project constraints and must/never checks.
+- `CI / Test / Evidence` decides whether the result can be accepted.
+- For the higher-level explanation, see [docs/agent-governance-overview.md](../../docs/agent-governance-overview.md).
+
+## Load Order
 
 ### 1. Core Layer
 
@@ -33,7 +33,7 @@ Use the workflow layer when the task involves routing, handoff, boundary changes
 - `rules/workflow/selection.md`
 - `rules/workflow/stop.md`
 - `PIG_SKILLS_RULE_PROFILE=router|refinement`
-- `PIG_SKILLS_RULE_SKILL=workflow-router|spec-refinement`
+- `PIG_SKILLS_RULE_SKILL=workflow-router|spec`
 
 ### 3. Coding Layer
 
@@ -80,7 +80,7 @@ Use the review layer when the task involves code review, security review, perfor
 
 ### 5. Product / Docs Layer
 
-Use the product/docs layer when the task involves requirement intake, domain modeling, API docs, knowledge capture, or contract writing.
+Use the product/docs layer when the task involves requirement intake, reverse-engineered business facts, domain modeling, API docs, knowledge capture, or contract writing.
 
 - `rules/product/index.md`
 - `rules/product/intake.md`
@@ -96,7 +96,7 @@ Use the product/docs layer when the task involves requirement intake, domain mod
 - `rules/docs/examples.md`
 - `rules/docs/capture-summary.md`
 - `PIG_SKILLS_RULE_PROFILE=intake|modeling|api|capture`
-- `PIG_SKILLS_RULE_SKILL=product-intake|domain-modeling|api-docs|knowledge-capture`
+- `PIG_SKILLS_RULE_SKILL=spec|domain-modeling|extract-business-facts|api-docs|knowledge-capture`
 
 ### 6. Discovery Rules
 

package/skills/references/skill-authoring-standard.md

@@ -63,8 +63,8 @@ Make every skill easy for AI to detect, cheap to read, and hard to misuse.
 - Negative replay scenarios
 
 ## Template Selection
-- Short template: `workflow-router`, `product-intake`, `knowledge-capture`, `api-docs`, `test-design`, `domain-modeling`, `project-bootstrap`, `environment-deploy`
-- Enhanced template: `spec-refinement`, `technical-design`, `feature-build`, `code-review`, `security-review`, `performance-check`
+- Short template: `workflow-router`, `knowledge-capture`, `api-docs`, `test-design`, `domain-modeling`, `project-bootstrap`, `environment-deploy`
+- Enhanced template: `spec`, `technical-design`, `feature-build`, `code-review`, `security-review`, `performance-check`, `extract-business-facts`
 
 ## Quality Bar
 - A model should know whether to use the skill in under 10 seconds.