engineering-intelligence 0.8.1 → 1.1.0

package/templates/canonical/skills/ongoing-learning-engine/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ongoing-learning-engine
+description: Handles post-initialization continuous learning by detecting uncertainty, logging learning events, triggering targeted re-discovery, updating memory with newly learned patterns, tracking knowledge freshness scores, and enforcing staleness detection rules.
+version: 3.0.0
+---
+
+# Ongoing Learning Engine
+
+Continuously maintain and improve the AI's understanding of a codebase after initial discovery. This engine activates whenever the AI encounters areas it does not understand, when code changes invalidate existing knowledge, or when knowledge freshness degrades below acceptable thresholds.
+
+This capability does not modify product code.
+
+## Inputs
+
+- Current task context (what the AI is trying to do when uncertainty is encountered)
+- Repository root path
+- Existing knowledge base, memory, and context documents
+- Optional: specific module or area to re-learn
+- Optional: trigger event (uncertainty, staleness, explicit request)
+
+## Trigger Conditions
+
+The ongoing learning engine activates under these conditions:
+
+| Trigger | Condition | Action |
+|---|---|---|
+| **Uncertainty encountered** | AI cannot confidently answer a question about the codebase | Log uncertainty event, initiate targeted re-discovery |
+| **Staleness threshold** | Knowledge freshness score drops below 60 for a module | Trigger incremental re-scan of the stale module |
+| **Code change detected** | Files in a module changed since last knowledge update | Queue module for freshness re-evaluation |
+| **Explicit request** | User asks to re-learn or refresh understanding of an area | Full re-discovery of specified scope |
+| **Convention drift** | Detected patterns deviate from documented conventions | Log drift event, update conventions |
+| **New dependency** | A new package/dependency is added to the project | Scan and document the new dependency |
+
+## Procedure
+
+1. **Detect uncertainty** — Monitor for these uncertainty signals during any task:
+   - Unable to locate a file or module referenced in knowledge base
+   - Code structure does not match documented architecture
+   - An import path or API endpoint has changed
+   - A function signature or behavior differs from documentation
+   - A convention violation is found in new code (drift vs intentional change)
+   - Business logic encountered that has no corresponding documentation
+
+2. **Log uncertainty event** — Write to `.engineering-intelligence/events/uncertainty-log.md`:
+
+   ```markdown
+   ## <timestamp> — Uncertainty Event
+
+   - **Trigger**: <what the AI was doing>
+   - **Area**: <module/file/concept>
+   - **Type**: missing | outdated | contradictory | ambiguous
+   - **Severity**: low | medium | high | critical
+   - **Description**: <what is uncertain and why>
+   - **Current knowledge**: <what the existing docs say>
+   - **Observed reality**: <what the code actually shows>
+   - **Resolution**: pending | resolved | deferred
+   ```
+
+3. **Classify the uncertainty** — Determine the appropriate response:
+
+   | Type | Description | Response |
+   |---|---|---|
+   | **Missing** | No documentation exists for this area | Trigger targeted re-discovery |
+   | **Outdated** | Documentation exists but is stale | Trigger incremental sync of affected documents |
+   | **Contradictory** | Documentation contradicts code evidence | Flag for human review, update with code-as-truth |
+   | **Ambiguous** | Multiple interpretations are plausible | Log both interpretations, ask for clarification |
+
+4. **Execute targeted re-discovery** — For the specific area of uncertainty:
+   - Re-scan only the affected module/directory (not the full repository)
+   - Compare new findings against existing documentation
+   - Identify what changed and what is new
+   - Use `codebase-discovery-engine` scanning techniques but scoped to the specific area
+
+5. **Update knowledge** — Apply changes to the appropriate knowledge documents:
+   - Update knowledge base documents with corrected information
+   - Add `Last updated:` timestamp to modified sections
+   - Preserve evidence citations — update with new file paths/line numbers
+   - Record the update in the uncertainty log as `resolved`
+
+6. **Durability check** — Before writing any new pattern or fact to memory, apply these filters:
+   - **Will this still be relevant after 5+ more changes?** If no → do not store in memory
+   - **Is this a project-wide pattern or a local implementation detail?** If local → do not store in memory
+   - **Does this duplicate existing memory?** If yes → merge rather than add
+   - **Is this a transient state or a durable decision?** If transient → log in events, not memory
+
+7. **Track knowledge freshness** — Maintain freshness scores per module:
+
+   ```markdown
+   ## Knowledge Freshness Tracker
+
+   | Module | Last Scanned | Last Code Change | Freshness Score | Status |
+   |---|---|---|---|---|
+   | auth/ | 2024-01-15 | 2024-01-20 | 45 | 🔴 Stale |
+   | api/ | 2024-01-18 | 2024-01-18 | 95 | 🟢 Fresh |
+   | ... | ... | ... | ... | ... |
+   ```
+
+   **Freshness score calculation:**
+   - Start at 100 when a module is scanned
+   - Subtract 5 points per day since last scan if code has changed
+   - Subtract 2 points per day since last scan if code has NOT changed (knowledge can still drift)
+   - Subtract 10 points per file changed in module since last scan
+   - Floor at 0, cap at 100
+
+8. **Staleness detection** — Apply these rules continuously:
+
+   | Rule | Threshold | Action |
+   |---|---|---|
+   | Module freshness < 60 | Score drops below 60 | Queue for targeted re-discovery |
+   | Module freshness < 30 | Score drops below 30 | Flag as critical, prioritize re-discovery |
+   | No scan in 30 days | 30 days elapsed | Flag for freshness check regardless of score |
+   | >10 files changed since scan | File change count | Trigger immediate re-scan |
+   | Architecture document stale | Any architecture doc with freshness < 50 | Trigger full architecture re-assessment |
+
+9. **Generate learning summary** — Periodically (or on request) produce a learning summary:
+
+   ```markdown
+   ## Learning Summary — <date range>
+
+   ### Uncertainty Events
+   - Total events: <N>
+   - Resolved: <N>
+   - Pending: <N>
+   - Deferred: <N>
+
+   ### Knowledge Updates
+   - Documents updated: <list>
+   - Memory entries added: <N>
+   - Memory entries revised: <N>
+   - Memory entries retired: <N>
+
+   ### Freshness Overview
+   - Modules scanned: <N>
+   - Average freshness: <score>
+   - Stale modules (< 60): <list>
+   - Critical modules (< 30): <list>
+
+   ### Patterns Learned
+   - <new patterns discovered this period>
+
+   ### Open Questions
+   - <questions that need human input>
+   ```
+
+## Output Files
+
+| File | Purpose |
+|---|---|
+| `.engineering-intelligence/events/uncertainty-log.md` | Append-only log of all uncertainty events |
+| `.engineering-intelligence/reports/FRESHNESS-report.md` | Current freshness scores per module (shared with `staleness-detector`) |
+| Updated knowledge base documents | Corrected or expanded knowledge |
+| Updated memory documents | New durable patterns and decisions |
+
+## Quality Gates
+
+- [ ] Every uncertainty event is logged before any re-discovery begins
+- [ ] Uncertainty events include type, severity, and description
+- [ ] Targeted re-discovery scopes to the affected module only (not full repo)
+- [ ] Durability check is applied before any memory write
+- [ ] Knowledge freshness scores are calculated using the defined formula
+- [ ] Staleness thresholds trigger appropriate actions
+- [ ] Updated documents preserve evidence citation format
+- [ ] Learning summary is accurate and reflects actual events
+- [ ] No transient implementation details are stored in memory
+- [ ] Contradictory findings are flagged for human review (not silently resolved)
+
+## Cross-References
+
+- Depends on: `codebase-discovery-engine` (for targeted re-discovery techniques)
+- Uses: `staleness-detector` (for freshness scoring), `incremental-sync-engine` (for knowledge updates)
+- Consumed by: `engineering-intelligence-skill`, `engineering-orchestrator`
+- Feeds into: `.engineering-intelligence/events/uncertainty-log.md`, all knowledge base documents
+- Related: `convention-detector` (for convention drift detection)
+
+This capability does not modify product code.

package/templates/canonical/skills/operations-readiness-engine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: operations-readiness-engine
+description: Produces deployment, observability, rollback, and runbook readiness artifacts for production-bound AI-DLC changes.
+version: 1.0.0
+---
+
+# Operations Readiness Engine
+
+Use this skill when a change affects deployment, infrastructure, runtime behavior, SLOs, data migrations, incident response, or production monitoring.
+
+## Procedure
+
+1. Identify deployment target, environment variables, infrastructure files, CI/CD gates, and runtime services.
+2. Define release strategy: normal deploy, canary, blue/green, feature flag, or manual rollout.
+3. Define rollback plan and data recovery constraints.
+4. Define observability: metrics, traces, logs, dashboards, alerts, and ownership.
+5. Confirm production readiness with objective gates.
+
+## Outputs
+
+Write `.engineering-intelligence/aidlc/operations/operations-readiness.md`:
+
+```markdown
+# Operations Readiness
+
+## Deployment Scope
+- <services, packages, infrastructure>
+
+## Release Strategy
+- Strategy: <normal|canary|blue-green|feature-flag|manual>
+- Human approvals required: <yes/no and why>
+
+## Observability
+| Signal | Source | Threshold | Owner | Runbook |
+|---|---|---|---|---|
+
+## Rollback
+- Code rollback:
+- Data rollback:
+- Configuration rollback:
+
+## Readiness Gates
+- [ ] Build passes
+- [ ] Tests pass
+- [ ] Migrations are backward compatible or downtime is approved
+- [ ] Alerts/runbooks exist for changed failure modes
+- [ ] Secrets and environment variables are documented securely
+```
+
+## Rules
+
+- Never execute production deployment without explicit user approval.
+- Mark unknown production constraints in `open-questions.md`.
+- For database changes, require backward-compatible migration planning unless downtime is approved.

package/templates/canonical/skills/performance-analysis-engine/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: performance-analysis-engine
+description: Identifies performance issues through static analysis of database query patterns, frontend bundle size, render performance, API response patterns, and caching opportunities. Use during initialization, before releases, or when performance-sensitive changes are detected.
+version: 3.0.0
+---
+
+# Performance Analysis Engine
+
+Identify performance risks and optimization opportunities through evidence-based static analysis of code patterns, queries, bundles, and caching strategies.
+
+## Inputs
+
+- Repository root path
+- Mode: `full` (comprehensive analysis) or `targeted` (specific area or post-change)
+- Optional: scope constraints (specific modules, change diff)
+- Optional: previous assessment (`knowledge-base/21-performance-assessment.md`) for delta comparison
+
+## Procedure
+
+1. **Database Query Pattern Analysis** — Scan data access layers for:
+
+   | Pattern | Risk | Detection Method |
+   |---|---|---|
+   | N+1 queries | High | Loop containing query calls, ORM eager/lazy loading misuse |
+   | Missing indexes | Medium | Queries filtering/sorting on non-indexed columns |
+   | Unbounded queries | High | SELECT without LIMIT, missing pagination |
+   | Full table scans | Medium | Queries without WHERE clauses on large tables |
+   | Unnecessary joins | Low | Joins fetching unused columns |
+   | Missing connection pooling | Medium | New connection per request pattern |
+
+   Cross-reference with schema definitions and ORM configuration.
+
+2. **Bundle Size Analysis** (frontend projects) — Assess:
+
+   | Check | Description |
+   |---|---|
+   | Bundle composition | Identify largest dependencies by size contribution |
+   | Tree-shaking gaps | Imports that prevent effective tree-shaking |
+   | Code splitting | Missing dynamic imports for route-level splitting |
+   | Duplicate dependencies | Same library bundled at multiple versions |
+   | Dead code | Exported modules never imported elsewhere |
+   | Asset optimization | Uncompressed images, unminified resources |
+
+   Read build configuration (webpack, vite, esbuild, etc.) to understand current optimization setup.
+
+3. **Render Performance Patterns** (frontend projects) — Identify:
+
+   | Pattern | Risk | Detection Method |
+   |---|---|---|
+   | Unnecessary re-renders | High | Components without memoization receiving stable props |
+   | Missing `useMemo`/`useCallback` | Medium | Expensive computations in render path |
+   | Large component trees | Medium | Deeply nested components without virtualization |
+   | Layout thrashing | High | DOM reads interleaved with writes |
+   | Missing virtualization | High | Lists rendering >100 items without windowing |
+   | Unoptimized images | Medium | Missing lazy loading, no responsive sizes |
+
+4. **API Response Time Patterns** — Analyze:
+
+   | Check | Description |
+   |---|---|
+   | Waterfall requests | Sequential API calls that could be parallelized |
+   | Over-fetching | Endpoints returning significantly more data than consumed |
+   | Under-fetching | Multiple requests needed where one could suffice |
+   | Missing pagination | List endpoints without page size limits |
+   | Synchronous heavy operations | Long-running tasks blocking request handlers |
+   | Missing timeouts | External API calls without timeout configuration |
+
+5. **Caching Opportunities** — Identify:
+
+   | Opportunity | Evidence |
+   |---|---|
+   | Repeated identical queries | Same query executed multiple times per request |
+   | Static data fetched dynamically | Configuration or reference data loaded on every request |
+   | Missing HTTP cache headers | Responses for stable resources without Cache-Control |
+   | Computation-heavy endpoints | Endpoints with expensive but deterministic calculations |
+   | Missing CDN utilization | Static assets served from application server |
+   | Session/user-level caching | Per-user data re-fetched on every request |
+
+   Review existing caching infrastructure (Redis, Memcached, in-memory, HTTP) and identify gaps.
+
+6. **Generate Assessment** — Write findings to `knowledge-base/21-performance-assessment.md`.
+
+## Output Format
+
+Write `knowledge-base/21-performance-assessment.md`:
+
+```markdown
+# Performance Assessment
+
+## Meta
+- Generated: <ISO timestamp>
+- Mode: full | targeted
+- Scope: <what was examined>
+- Overall risk: low | medium | high | critical
+
+## Database Query Patterns
+| Issue | Location | Risk | Recommendation |
+|---|---|---|---|
+| N+1 query | src/users/service.ts:45 | High | Add eager loading for user.posts |
+
+## Bundle Analysis
+| Metric | Value | Status |
+|---|---|---|
+| Total bundle size | 1.2 MB | concern |
+| Largest dependency | moment.js (320 KB) | Replace with date-fns |
+
+## Render Performance
+| Issue | Component | Risk | Recommendation |
+|---|---|---|---|
+| Missing memoization | UserList | Medium | Wrap with React.memo |
+
+## API Patterns
+| Issue | Endpoint | Risk | Recommendation |
+|---|---|---|---|
+| Waterfall requests | /dashboard | High | Parallelize data fetching |
+
+## Caching Opportunities
+| Opportunity | Location | Impact |
+|---|---|---|
+| Static config fetched per request | src/config/loader.ts | High |
+
+## Recommendations
+1. <prioritized optimization actions with estimated impact>
+
+## Evidence
+- <file path citations for all findings>
+
+---
+*This performance assessment did not modify product code.*
+```
+
+## Rules
+
+- Every finding must cite a specific file path and line number or code pattern
+- Risk assessment must consider actual usage patterns, not theoretical worst cases
+- Bundle analysis findings must reference build configuration evidence
+- Do not recommend premature optimization — prioritize by measured or evidenced impact
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] All findings cite specific file paths or code patterns
+- [ ] Database query issues distinguish between ORM-generated and raw queries
+- [ ] Bundle analysis references build configuration
+- [ ] Render performance findings are framework-aware (React, Vue, Angular, etc.)
+- [ ] Caching recommendations consider existing infrastructure
+- [ ] Recommendations are prioritized by estimated impact
+- [ ] Report ends with the "did not modify product code" statement
+
+## Cross-References
+
+- Depends on: `deep-project-knowledge-extractor` (project structure and technology understanding)
+- Used by: `engineering-intelligence-skill`, `impact-analysis-engine` (performance risk scoring)
+- Updates: `knowledge-base/21-performance-assessment.md`
+
+This capability is analytical only. It must not modify product code.

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

@@ -0,0 +1,127 @@
+---
+name: pr-intelligence-engine
+description: Generates intelligent PR descriptions, reviewer suggestions, impact summaries, and split recommendations from change records and git intelligence. Use before submitting or reviewing pull requests.
+version: 3.0.0
+---
+
+# PR Intelligence Engine
+
+Produce evidence-backed PR artifacts that accelerate review cycles and improve change quality.
+
+## Inputs
+
+- Change records from `.changes/CHG-XXX-*.md`
+- Git diff or commit range for the PR
+- Ownership mapping from `git-intelligence-engine` (`.engineering-intelligence/reports/GIT-intelligence.md`)
+- Impact report from `impact-analysis-engine` (when available)
+- Architecture decisions from `knowledge-base/`
+
+## Procedure
+
+1. **Analyze Change Scope** — Parse the diff or commit range to determine:
+   - Files modified, added, deleted
+   - Total lines changed (additions + deletions)
+   - Modules touched (distinct top-level directories or packages)
+   - Change classification (feature, bugfix, refactor, infrastructure, docs)
+
+2. **Generate PR Description** — From change records and diff, produce:
+
+   ```markdown
+   ## What
+   <concise summary of what changed and why>
+
+   ## Why
+   <link to change record CHG-XXX, issue/ticket if available>
+
+   ## How
+   <technical approach summary — key design decisions>
+
+   ## Impact
+   <blast radius summary from impact analysis>
+
+   ## Testing
+   <tests added/modified, validation performed>
+
+   ## Migration / Rollback
+   <if applicable — schema changes, feature flags, rollback steps>
+   ```
+
+3. **Suggest Reviewers** — Using ownership mapping from `git-intelligence-engine`:
+
+   | Priority | Criteria |
+   |---|---|
+   | Required | Primary owner of any modified module |
+   | Recommended | Secondary owner with recent activity in modified files |
+   | Optional | Contributors to change-coupled files not in the diff |
+   | Domain expert | Owner of upstream/downstream modules from impact analysis |
+
+   Flag when no active owner exists for a modified module (orphaned module risk).
+
+4. **Generate Impact Summary** — Produce a reviewer-focused impact digest:
+   - Risk level (from impact report or assessed from diff)
+   - Breaking changes (API contracts, schema migrations)
+   - Cross-service effects (if any)
+   - Intelligence artifacts that will need sync after merge
+
+5. **Evaluate PR Size and Suggest Split** — If the PR exceeds thresholds:
+
+   | Metric | Threshold | Action |
+   |---|---|---|
+   | Total lines changed | >500 | Suggest split |
+   | Modules touched | >3 | Suggest split |
+   | Mixed concerns | Feature + refactor | Suggest split |
+   | Schema + code | Migration + logic | Suggest split |
+
+   When suggesting split, propose concrete split boundaries:
+   - Group by module or concern
+   - Identify which changes can land independently
+   - Suggest merge order if dependencies exist between splits
+
+6. **Check Architecture Compliance** — Compare changes against:
+   - `knowledge-base/05-architecture-decisions.md` (ADRs)
+   - `knowledge-base/06-conventions-and-standards.md`
+   - Module boundary rules from `dependency-graph.json`
+
+   Flag violations with evidence:
+
+   | Violation Type | Example |
+   |---|---|
+   | Dependency direction | Service A importing from Service B's internals |
+   | Convention breach | Naming pattern, file structure deviation |
+   | ADR contradiction | Change conflicts with recorded architecture decision |
+   | Missing ADR | Architectural change without corresponding decision record |
+
+## Output Format
+
+Generate the following artifacts (do not write to the repository — present to the user):
+
+- **PR description** — Markdown ready to paste into PR body
+- **Reviewer suggestions** — Ranked list with rationale
+- **Impact summary** — Reviewer-focused digest
+- **Split recommendations** — Only if thresholds are exceeded
+- **Architecture flags** — Only if violations are detected
+
+## Rules
+
+- PR descriptions must reference change records (CHG-XXX) when available
+- Reviewer suggestions must cite ownership evidence, not guess from file paths
+- Never suppress architecture violations — always surface them
+- Split suggestions must include concrete boundaries, not vague advice
+- This capability is analytical only — it must not modify product code
+
+## Quality Gates
+
+- [ ] PR description covers what, why, how, impact, and testing
+- [ ] Reviewer suggestions cite ownership data with evidence
+- [ ] Impact summary includes risk level and blast radius
+- [ ] Split recommendations (if any) propose concrete boundaries
+- [ ] Architecture violations cite specific ADRs or conventions breached
+- [ ] All claims reference change records, diffs, or intelligence artifacts
+
+## Cross-References
+
+- Depends on: `git-intelligence-engine` (ownership mapping), `impact-analysis-engine` (impact reports), `change-detection-engine` (change records)
+- Used by: `engineering-intelligence-skill`
+- Consumed by: `engineering-change-review`
+
+This capability is analytical only. It must not modify product code.

package/templates/canonical/skills/requirement-scoper/SKILL.md

@@ -24,13 +24,14 @@ Act as a detailed Business Analyst and Technical Architect persona. Analyze the
 
 2. **Formulate Scoping Questions** — Identify gaps, ambiguities, and edge cases. Ask the user 3 to 5 targeted questions covering:
    - **Business Value & Scope**: What are the limits of the MVP?
+   - **Agile Story Shape**: What user role, user goal, priority, dependencies, and release expectation apply?
    - **Technical Strategy**: Which specific database, caching, or third-party integrations are expected?
    - **Edge Cases**: How should errors, rate limits, or validation failures be handled?
    - **UI/UX (if applicable)**: What configuration or user feedback is expected?
 
 3. **Iterate with User** — Wait for user responses. Adjust assumptions based on their answers.
 
-4. **Generate Final Requirement Prompt** — Once requirements are clear, output a comprehensive requirements document to `knowledge-base/19-requirements.md` and formulate the finalized prompt for the development agent.
+4. **Generate Final Requirement Prompt** — Once requirements are clear, output a comprehensive requirements document to `knowledge-base/19-requirements.md`, update Agile artifacts under `.engineering-intelligence/aidlc/agile/`, and formulate the finalized prompt for the development agent.
 
 ## Output Format
 
@@ -47,10 +48,21 @@ The final requirements document `knowledge-base/19-requirements.md` must follow
 - **System Boundaries & Dependencies**: <Files/modules affected based on graph mappings>
 - **Edge Cases & Failure Modes**: <Exactly how to handle failures, retries, limits>
 
-## 3. Iterated QA Log
+## 3. Agile Delivery Model
+- **Epic**: <epic or initiative>
+- **User Story**: As a <persona>, I want <capability>, so that <outcome>.
+- **Priority**: <P0/P1/P2 or project convention>
+- **Acceptance Criteria**:
+  - Given <context>, when <action>, then <observable result>.
+- **Definition of Ready**:
+  - <ready gate status>
+- **Definition of Done**:
+  - <done gate expectations>
+
+## 4. Iterated QA Log
 <Questions asked and answers received during scoping>
 
-## 4. Finalized Implementation Prompt
+## 5. Finalized Implementation Prompt
 Provide the exact prompt to pass to the coding agent to execute this change:
 ```text
 /engineering-intelligence <Fully detailed requirements and file scope here>
@@ -62,10 +74,12 @@ Provide the exact prompt to pass to the coding agent to execute this change:
 - **Do not modify product code** — this skill is strictly for scoping and analysis.
 - Do not make assumptions on ambiguities; always ask clarifying questions.
 - Base questions and plans on project graph mappings and existing memory files.
+- Keep Agile artifacts synchronized with the final requirement prompt.
 
 ## Quality Gates
 
 - [ ] Clear business goals and technical boundaries defined.
 - [ ] At least 3 scoping questions asked and logged.
+- [ ] User story, acceptance criteria, priority, dependencies, and Ready/Done gates are documented.
 - [ ] Finalized prompt maps exact files and modules.
 - [ ] Output does not contain any code modification.