engineering-intelligence 0.2.0 → 0.4.0

package/templates/canonical/skills/testing-intelligence-engine/SKILL.md

@@ -1,10 +1,126 @@
 ---
 name: testing-intelligence-engine
 description: Determines risk-based testing needs for engineering changes and identifies coverage gaps in critical runtime flows. Use during implementation and validation.
+version: 3.0.0
 ---
 
-# Testing Intelligence
+# Testing Intelligence Engine
 
-Inspect existing test patterns and identify the smallest sufficient validation for the impacted behavior. Include unit, integration, end-to-end, migration, security, or operational checks when risk requires them.
+Determine the minimum sufficient test coverage for a change based on risk assessment and existing test patterns.
 
-When documenting broad testing posture, update `knowledge-base/17-testing-strategy.md`. For individual changes, record tests run and remaining gaps in the relevant `.changes/` entry.
+## Inputs
+
+- Impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- Existing test patterns in the repository
+- Change classification (feature, bugfix, refactor, etc.)
+
+## Risk-Based Test Selection Matrix
+
+| Risk Level | Unit Tests | Integration Tests | E2E Tests | Security Tests | Migration Tests | Manual |
+|---|---|---|---|---|---|---|
+| **Low** | Changed functions | — | — | — | — | — |
+| **Medium** | Changed + adjacent | Affected APIs | — | — | — | — |
+| **High** | Changed + adjacent | Affected APIs | Critical paths | If auth touched | If schema touched | Recommended |
+| **Critical** | Comprehensive | All affected | Full suite | Required | Required | Required |
+
+## Procedure
+
+1. **Assess Existing Coverage** — Scan the test suite:
+   - Identify test framework(s) in use (Jest, Mocha, pytest, Go testing, etc.)
+   - Locate test directories and naming patterns
+   - Map tests to source files (by convention or configuration)
+   - Identify untested critical paths
+
+2. **Map Change to Tests** — Using the impact report:
+   - List source files/functions changed
+   - Find existing tests covering those files
+   - Identify tests that should exist but don't (coverage gaps)
+
+3. **Determine Required Tests** — Using the risk matrix above:
+
+   **For `bugfix`**:
+   - Regression test reproducing the original bug (required)
+   - Verify fix doesn't break adjacent behavior
+
+   **For `feature`**:
+   - Unit tests for new functions/methods
+   - Integration tests for new API endpoints or service interactions
+   - Happy path + error path coverage
+
+   **For `refactor`**:
+   - All existing tests must still pass (no new tests needed if behavior unchanged)
+   - Add tests if coverage gaps are discovered during refactoring
+
+   **For `architecture` / `security`**:
+   - Boundary tests between new/changed architectural boundaries
+   - Negative-path and permission tests for security changes
+   - Data migration and rollback tests for schema changes
+
+4. **Identify Coverage Gaps** — Report:
+   - Critical paths with no test coverage
+   - Changed behavior with no corresponding test
+   - Error paths and edge cases not covered
+
+5. **Recommend Test Strategy** — For the specific change, recommend:
+   - Test files to create or modify
+   - Test cases to write (describe what, not write the test code)
+   - Validation commands to run
+
+## Output
+
+### Per-Change Testing (in `.changes/CHG-XXX-*.md`)
+
+```markdown
+## Tests
+- Added: <test file> — <what it tests>
+- Modified: <test file> — <what changed>
+- Run command: `npm test` / `pytest` / etc.
+- Results: X passed, Y failed, Z skipped
+- Coverage gaps: <untested areas remaining>
+```
+
+### Broad Testing Strategy (in `knowledge-base/17-testing-strategy.md`)
+
+Only update when documenting project-wide testing posture:
+
+```markdown
+# Testing Strategy
+
+## Test Framework
+- Framework: <name and version>
+- Configuration: <config file path>
+
+## Test Organization
+| Directory | Type | Coverage |
+|---|---|---|
+| test/unit/ | Unit tests | Core business logic |
+| test/integration/ | Integration | API endpoints |
+
+## Coverage Gaps
+- <critical untested areas>
+
+## Running Tests
+- All tests: `<command>`
+- Specific suite: `<command>`
+- Coverage report: `<command>`
+```
+
+## Rules
+
+- Recommend tests proportional to risk — don't mandate full-suite runs for low-risk changes
+- Always note when validation was not actually run (only recommended)
+- Never claim test coverage without checking existing tests
+- Record test results honestly, including failures
+
+## Quality Gates
+
+- [ ] Impact report was consulted for risk level
+- [ ] Test recommendations match the risk level
+- [ ] Existing test coverage was checked before recommending new tests
+- [ ] Coverage gaps in critical paths are flagged
+
+## Cross-References
+
+- Depends on: `impact-analysis-engine` (for risk assessment)
+- Used by: `engineering-intelligence-skill` (step 4: tests and validation)
+- Updates: `knowledge-base/17-testing-strategy.md` (broad posture only)

package/templates/canonical/workflows/analyze-impact.md

@@ -6,8 +6,30 @@ description: Analyze the impact of a proposed change or existing diff and write
 
 Use `change-detection-engine`, `impact-analysis-engine`, and `graph-engine` when graph intelligence is missing or stale.
 
-Analyze the user-supplied proposed change, working-tree diff, commit/range, or explicit changed paths. If the scope is ambiguous, ask for it instead of assuming.
+## Input
 
-Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md` covering analysis mode and scope, graph inputs, direct and indirect impact, risks, validation needs, intelligence artifacts needing synchronization, evidence, and uncertainties.
+Analyze the user-supplied scope: proposed change description, working-tree diff, commit/range, or explicit changed paths. If the scope is ambiguous, ask for clarification instead of assuming.
 
-This workflow may write intelligence reports or refresh necessary graph context. It must not modify product code.
+## Output
+
+Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md` covering:
+
+| Section | Content |
+|---|---|
+| Analysis mode & scope | `proposal` or `diff`, what was examined |
+| Graph inputs | Graphs consulted, refreshed, or missing |
+| Direct impact | Files and systems directly affected |
+| Indirect impact | Downstream dependencies and consumers |
+| Risk assessment | Risk level with justification |
+| Validation needs | Tests and checks required |
+| Intelligence artifacts | Knowledge, memory, context, events, and graphs needing sync |
+| Evidence | File path citations for all claims |
+| Unknowns | Areas where impact is uncertain |
+
+## Rules
+
+- Ask for scope clarification when ambiguous — never assume
+- Consult graph intelligence before tracing impact manually
+- Score risk with evidence-based justification
+- This workflow may write intelligence reports or refresh necessary graph context
+- It must not modify product code

package/templates/canonical/workflows/engineering-intelligence.md

@@ -4,8 +4,25 @@ description: Implement an engineering request with impact analysis, tests, valid
 
 # Engineering Intelligence
 
-Use the `engineering-intelligence` capability for the user's accompanying request.
+Use the `engineering-intelligence-skill` capability for the user's accompanying request.
 
-Read project intelligence and graph artifacts, write a pre-change `.engineering-intelligence/reports/IMP-XXX-<summary>.md` impact report, implement the requested work, add or update appropriate tests, validate the result, incrementally synchronize affected knowledge/memory/context/event/graph artifacts, and write the next `.changes/CHG-XXX-<summary>.md` entry referencing related reports. Run review responsibility before completion when change risk is high.
+## Pipeline
 
-Finish with changed code, tests and validation, affected systems, synchronized artifacts and graphs, related reports, and unresolved risks.
+1. **Read Intelligence** — Consult `knowledge-base/`, `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/graph/`
+2. **Write Impact Report** — Create `.engineering-intelligence/reports/IMP-XXX-<summary>.md` before any code edit
+3. **Implement** — Make the requested code changes following established patterns
+4. **Test** — Add/update tests proportional to risk; execute and record results
+5. **Validate** — Run available linters, type checks, and test suites
+6. **Sync Intelligence** — Incrementally update only affected knowledge, memory, context, event, graph artifacts
+7. **Record Change** — Write `.changes/CHG-XXX-<summary>.md` referencing related reports
+8. **Review Gate** — For high-risk changes, run engineering-change review before completion
+
+## Completion Report
+
+Finish with:
+- Code changes made (files, what changed)
+- Tests run and results (pass/fail counts)
+- Affected systems and services
+- Synchronized intelligence artifacts
+- Related reports (IMP-XXX, REV-XXX)
+- Unresolved risks or follow-ups

package/templates/canonical/workflows/initialize-engineering-intelligence.md

@@ -4,8 +4,35 @@ description: Initialize evidence-based engineering intelligence for the current
 
 # Initialize Engineering Intelligence
 
-Use the `initialize-engineering-intelligence` capability.
+Use the `initialize-intelligence-skill` capability.
 
-Analyze this repository thoroughly without changing product code. Generate `knowledge-base/`, validate it against evidence, generate `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/events/`, and build `.engineering-intelligence/graph/` JSON graphs plus `architecture-map.md`. Write `.changes/CHG-000-initialization.md`.
+## What This Does
 
-Do not fabricate details. Mark uncertainty clearly and finish with the created artifacts and human-review items.
+Analyzes this repository thoroughly without changing product code. Produces a complete project intelligence baseline.
+
+## Outputs Generated
+
+| Category | Path | Content |
+|---|---|---|
+| Knowledge Base | `knowledge-base/` | 16 evidence-backed documents (00-15) |
+| Memory | `.engineering-intelligence/memory/` | 5 durable decision/pattern documents |
+| Context | `.engineering-intelligence/context/` | 6 compact navigation maps |
+| Events | `.engineering-intelligence/events/` | 5 change-event guidance documents |
+| Graphs | `.engineering-intelligence/graph/` | 4 JSON graphs + architecture-map.md |
+| History | `.changes/CHG-000-initialization.md` | Initialization record |
+
+## Execution Steps
+
+1. **Discover** — Scan repository for packages, runtimes, build systems, APIs, databases, auth, CI, and tests
+2. **Extract** — Generate knowledge-base documents with evidence citations
+3. **Validate** — Audit claims against source code; write validation report
+4. **Generate Memory** — Extract durable decisions and patterns
+5. **Generate Context** — Create concise AI navigation maps
+6. **Build Graphs** — Generate evidence-backed architecture graphs
+7. **Record** — Write initialization change record
+
+## Important
+
+- Do not fabricate details — mark uncertainty clearly
+- Every claim must cite evidence from the repository
+- Finish with: created artifacts, confidence assessment, and human-review items

package/templates/canonical/workflows/map-architecture.md

@@ -8,10 +8,21 @@ Use the `graph-engine` capability.
 
 Inspect repository evidence and generate or comprehensively refresh:
 
-- `.engineering-intelligence/graph/dependency-graph.json`
-- `.engineering-intelligence/graph/service-graph.json`
-- `.engineering-intelligence/graph/runtime-graph.json`
-- `.engineering-intelligence/graph/business-flow-graph.json`
-- `.engineering-intelligence/graph/architecture-map.md`
+| Artifact | Content |
+|---|---|
+| `.engineering-intelligence/graph/dependency-graph.json` | Module/package dependency relationships |
+| `.engineering-intelligence/graph/service-graph.json` | Service-to-service communication topology |
+| `.engineering-intelligence/graph/runtime-graph.json` | Runtime call flows and middleware chains |
+| `.engineering-intelligence/graph/business-flow-graph.json` | Business process flows across boundaries |
+| `.engineering-intelligence/graph/architecture-map.md` | Mermaid diagrams derived from JSON graphs |
 
-Use stable node IDs, evidence-backed confidence labels, explicit unknowns, and Mermaid diagrams. You may update graph-connected navigation context when necessary. Do not modify product code.
+## Requirements
+
+- Use stable node IDs across updates
+- Mark every edge with `verified`, `inferred`, or `unknown` confidence
+- Back every `verified` edge with evidence file paths
+- List unresolved relationships in the `unknowns` array
+- Derive Mermaid diagrams from JSON graph data — not hand-authored
+- Update graph-connected navigation context when necessary
+
+This workflow may update graph and context intelligence artifacts. It must not modify product code.

package/templates/canonical/workflows/review-engineering-change.md

@@ -6,6 +6,30 @@ description: Review changed engineering work, tests, graphs, and synchronized in
 
 Use `change-detection-engine` and `engineering-change-review`.
 
-Inspect the identified implementation diff or changed scope, associated impact report, test and validation evidence, graph consistency, and documentation/context synchronization.
+## Procedure
 
-Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with severity-ordered findings, evidence paths, test gaps, and stale-intelligence risks. Do not modify product code or auto-fix findings.
+1. **Detect scope** — Identify the implementation diff or changed scope
+2. **Read context** — Load associated impact report, test evidence, and graph artifacts
+3. **Review** — Inspect across five dimensions:
+
+| Dimension | What to Check |
+|---|---|
+| Implementation | Correctness, request fulfillment, error handling |
+| Tests | Coverage, execution, results, gaps |
+| Architecture | Boundary respect, pattern compliance, dependency direction |
+| Graph consistency | New/changed nodes and edges reflected |
+| Documentation sync | Knowledge, memory, context accuracy |
+
+4. **Write report** — Generate `.engineering-intelligence/reports/REV-XXX-<slug>.md` with:
+   - Severity-ordered findings (🔴 Blocker → 🟢 Positive)
+   - Evidence paths for each finding
+   - Test gaps and coverage concerns
+   - Stale-intelligence risks
+   - Verdict: Approved / Approved with findings / Changes required
+
+## Rules
+
+- Do not modify product code
+- Do not auto-fix findings — report only
+- Include positive observations alongside issues
+- Flag unrun validation honestly

package/templates/canonical/workflows/sync-engineering-intelligence.md

@@ -6,6 +6,24 @@ description: Incrementally synchronize intelligence artifacts for an identified
 
 Use `change-detection-engine`, `impact-analysis-engine`, and `incremental-sync-engine`.
 
-Read the supplied changed scope, diff, or completed change record. Create an impact report first if none exists for that scope. Update only affected knowledge, memory, context, event, graph, and report artifacts.
+## Procedure
 
-Standalone synchronization must not create a `.changes/CHG-XXX-*` implementation record and must not modify product code.
+1. **Detect scope** — Read the supplied changed scope, diff, or completed change record
+2. **Analyze impact** — Create an impact report first if none exists for this scope
+3. **Sync artifacts** — Update only affected intelligence:
+
+| Artifact Type | Engine | Update Rule |
+|---|---|---|
+| Knowledge Base | `knowledge-sync-engine` | Only docs mapped to the change type |
+| Memory | `memory-sync-engine` | Only if durable decisions changed |
+| Context | `context-sync-engine` | Only affected navigation maps |
+| Events | Direct update | Only if API/schema/auth contracts changed |
+| Graphs | `graph-engine` (incremental) | Only affected nodes and edges |
+| Reports | Impact report update | Add sync notes |
+
+## Rules
+
+- Standalone synchronization must not create `.changes/CHG-XXX-*` implementation records
+- Must not modify product code
+- Update only artifacts identified by the impact report
+- Preserve accurate existing content in all artifacts

package/templates/canonical/skills/engineering-intelligence/SKILL.md

@@ -1,21 +0,0 @@
----
-name: engineering-intelligence
-description: Executes engineering changes with impact analysis, implementation, tests, validation, and incremental synchronization of project intelligence. Use for feature, bugfix, update, refactor, architecture, infrastructure, or security requests.
----
-
-# Engineering Intelligence Workflow
-
-Use this workflow for implementation requests after project intelligence has been initialized.
-
-## Procedure
-
-1. Read relevant files from `knowledge-base/`, `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, and `.engineering-intelligence/graph/`. If missing, run the initialization capability first.
-2. Classify the request and write a pre-change `.engineering-intelligence/reports/IMP-XXX-<summary>.md` impact report before editing.
-3. Implement the requested change in the project code.
-4. Add or update relevant tests and execute the appropriate validation available in the project.
-5. Use incremental synchronization to update only affected knowledge-base, memory, context, event, graph, and report artifacts.
-6. Create the next `.changes/CHG-XXX-<summary>.md` record referencing related impact and any review reports.
-7. For high-risk changes, run engineering-change review before final reporting.
-8. Report code changes, tests run, affected systems, synchronized documentation/graph artifacts, and unresolved risks.
-
-Do not claim validation succeeded unless it ran successfully. Do not update unrelated documents merely to regenerate them.

package/templates/canonical/skills/initialize-engineering-intelligence/SKILL.md

@@ -1,32 +0,0 @@
----
-name: initialize-engineering-intelligence
-description: Initializes project engineering intelligence by analyzing repository evidence and generating knowledge, context, memory, event guidance, architecture graphs, and an initialization change record. Use when onboarding a repository or when asked to initialize engineering intelligence.
----
-
-# Initialize Engineering Intelligence
-
-Create a trustworthy project intelligence baseline. Analyze only evidence present in source code, configuration, tests, infrastructure, and existing documentation. Mark unknowns and uncertainties explicitly; never invent architecture, APIs, schemas, or business rules.
-
-## Outputs
-
-Generate:
-
-- `knowledge-base/00-project-overview.md` through `knowledge-base/15-validation-report.md`
-- `.engineering-intelligence/memory/` for durable decisions, rules, patterns, constraints, and technology decisions
-- `.engineering-intelligence/context/` for module, service, runtime, dependency, critical-path, and dangerous-area maps
-- `.engineering-intelligence/events/` for API, schema, auth, feature, and infrastructure change guidance
-- `.engineering-intelligence/graph/` for JSON dependency, service, runtime, and business-flow graphs plus a Mermaid architecture map
-- `.changes/CHG-000-initialization.md`
-
-## Procedure
-
-1. Discover repositories, packages, runtimes, build systems, entrypoints, CI, deployment, environment examples, databases, APIs, auth, and tests.
-2. Trace architecture and critical runtime flows from code evidence.
-3. Write the knowledge base with file-backed evidence and clearly labeled unknowns.
-4. Validate major documentation claims against the project and write `15-validation-report.md`.
-5. Generate compact durable memory and navigation context from validated findings.
-6. Use `graph-engine` to generate a full evidence-backed graph baseline and `architecture-map.md`.
-7. Generate change-event guidance and initialization history.
-8. Report generated artifacts, confidence limits, and areas requiring human confirmation.
-
-This initialization workflow documents and validates the project. It does not implement product changes.