engineering-intelligence 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/adapters/index.js +3 -3
- package/dist/adapters/index.js.map +1 -1
- package/dist/cli/index.js +24 -3
- package/dist/cli/index.js.map +1 -1
- package/dist/templates.d.ts +1 -1
- package/dist/templates.js +2 -2
- package/dist/templates.js.map +1 -1
- package/dist/validation/index.js +1 -1
- package/dist/validation/index.js.map +1 -1
- package/dist/visualizer/index.d.ts +2 -0
- package/dist/visualizer/index.d.ts.map +1 -0
- package/dist/visualizer/index.js +599 -0
- package/dist/visualizer/index.js.map +1 -0
- package/package.json +3 -3
- package/templates/canonical/agents/change-agent.md +58 -1
- package/templates/canonical/agents/engineering-orchestrator.md +69 -3
- package/templates/canonical/agents/knowledge-agent.md +59 -2
- package/templates/canonical/agents/quality-agent.md +59 -2
- package/templates/canonical/rules/engineering-intelligence.md +42 -13
- package/templates/canonical/skills/architecture-review-engine/SKILL.md +112 -3
- package/templates/canonical/skills/change-detection-engine/SKILL.md +82 -7
- package/templates/canonical/skills/change-history-engine/SKILL.md +125 -5
- package/templates/canonical/skills/context-sync-engine/SKILL.md +116 -9
- package/templates/canonical/skills/deep-project-knowledge-extractor/SKILL.md +171 -5
- package/templates/canonical/skills/engineering-change-review/SKILL.md +145 -9
- package/templates/canonical/skills/engineering-intelligence-skill/SKILL.md +168 -0
- package/templates/canonical/skills/graph-engine/SKILL.md +134 -14
- package/templates/canonical/skills/impact-analysis-engine/SKILL.md +125 -11
- package/templates/canonical/skills/incremental-sync-engine/SKILL.md +75 -10
- package/templates/canonical/skills/initialize-intelligence-skill/SKILL.md +130 -0
- package/templates/canonical/skills/knowledge-base-validator/SKILL.md +92 -7
- package/templates/canonical/skills/knowledge-sync-engine/SKILL.md +77 -8
- package/templates/canonical/skills/memory-sync-engine/SKILL.md +70 -8
- package/templates/canonical/skills/refactoring-planner/SKILL.md +143 -2
- package/templates/canonical/skills/testing-intelligence-engine/SKILL.md +119 -3
- package/templates/canonical/workflows/analyze-impact.md +25 -3
- package/templates/canonical/workflows/engineering-intelligence.md +20 -3
- package/templates/canonical/workflows/initialize-engineering-intelligence.md +30 -3
- package/templates/canonical/workflows/map-architecture.md +17 -6
- package/templates/canonical/workflows/review-engineering-change.md +26 -2
- package/templates/canonical/workflows/sync-engineering-intelligence.md +20 -2
- package/templates/canonical/skills/engineering-intelligence/SKILL.md +0 -21
- package/templates/canonical/skills/initialize-engineering-intelligence/SKILL.md +0 -32
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: initialize-intelligence-skill
|
|
3
|
+
description: Initializes project engineering intelligence by analyzing repository evidence and generating knowledge, context, memory, event guidance, architecture graphs, and an initialization change record. Invoke when onboarding a repository or when asked to initialize engineering intelligence.
|
|
4
|
+
version: 3.0.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Initialize Engineering Intelligence
|
|
8
|
+
|
|
9
|
+
Create a trustworthy, evidence-backed project intelligence baseline. Analyze only artifacts present in source code, configuration, tests, infrastructure, and existing documentation. Mark unknowns and uncertainties explicitly — never invent architecture, APIs, schemas, or business rules.
|
|
10
|
+
|
|
11
|
+
## Inputs
|
|
12
|
+
|
|
13
|
+
- Repository root path (current working directory by default)
|
|
14
|
+
- Optional: explicit scope constraints (monorepo package, service boundary)
|
|
15
|
+
|
|
16
|
+
## Outputs
|
|
17
|
+
|
|
18
|
+
Generate the following artifacts in order:
|
|
19
|
+
|
|
20
|
+
### Knowledge Base (`knowledge-base/`)
|
|
21
|
+
|
|
22
|
+
| Document | Purpose |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `00-project-overview.md` | Name, purpose, tech stack, repo structure summary |
|
|
25
|
+
| `01-repository-structure.md` | Directory tree, package boundaries, build artifacts |
|
|
26
|
+
| `02-architecture.md` | Layers, modules, boundaries, communication patterns |
|
|
27
|
+
| `03-runtime-flow.md` | Request lifecycle, startup, shutdown, async flows |
|
|
28
|
+
| `04-api-documentation.md` | Routes, endpoints, GraphQL schemas, RPC interfaces |
|
|
29
|
+
| `05-database.md` | Schemas, migrations, ORMs, data stores, caching |
|
|
30
|
+
| `06-authentication.md` | Auth flows, session management, RBAC, tokens |
|
|
31
|
+
| `07-frontend.md` | UI framework, routing, state management, components |
|
|
32
|
+
| `08-backend.md` | Server framework, middleware, service patterns |
|
|
33
|
+
| `09-infrastructure.md` | CI/CD, containers, cloud, deployment, environments |
|
|
34
|
+
| `10-integrations.md` | Third-party APIs, SDKs, webhooks, message queues |
|
|
35
|
+
| `11-complex-areas.md` | High-complexity modules, tricky logic, footguns |
|
|
36
|
+
| `12-technical-debt.md` | Known debt, deprecated patterns, migration needs |
|
|
37
|
+
| `13-onboarding.md` | Setup guide, dev workflow, common tasks |
|
|
38
|
+
| `14-glossary.md` | Domain terms, abbreviations, naming conventions |
|
|
39
|
+
| `15-validation-report.md` | Evidence audit of all claims made above |
|
|
40
|
+
|
|
41
|
+
### Durable Memory (`.engineering-intelligence/memory/`)
|
|
42
|
+
|
|
43
|
+
| Document | Content |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `architecture-decisions.md` | ADRs, architectural choices, rationale |
|
|
46
|
+
| `business-rules.md` | Domain rules, invariants, constraints from code |
|
|
47
|
+
| `coding-patterns.md` | Recurring patterns, conventions, idioms |
|
|
48
|
+
| `project-constraints.md` | Performance budgets, compatibility, regulatory |
|
|
49
|
+
| `technology-decisions.md` | Stack choices, version policies, deprecation plans |
|
|
50
|
+
|
|
51
|
+
### Navigation Context (`.engineering-intelligence/context/`)
|
|
52
|
+
|
|
53
|
+
| Document | Content |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `module-map.md` | Module names → paths → responsibilities |
|
|
56
|
+
| `service-map.md` | Services → ports → protocols → dependencies |
|
|
57
|
+
| `runtime-map.md` | Entry points → middleware chains → handlers |
|
|
58
|
+
| `critical-paths.md` | Revenue, auth, data-integrity flows |
|
|
59
|
+
| `dangerous-areas.md` | Fragile code, missing tests, race conditions |
|
|
60
|
+
| `dependency-map.md` | External deps → internal consumers → risk |
|
|
61
|
+
|
|
62
|
+
### Event Guidance (`.engineering-intelligence/events/`)
|
|
63
|
+
|
|
64
|
+
| Document | Trigger |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `api-changed.md` | When API routes, payloads, or contracts change |
|
|
67
|
+
| `schema-changed.md` | When database schemas or migrations change |
|
|
68
|
+
| `auth-changed.md` | When auth flows or permissions change |
|
|
69
|
+
| `feature-added.md` | When new user-facing features are introduced |
|
|
70
|
+
| `infrastructure-changed.md` | When CI, deployment, or infra config changes |
|
|
71
|
+
|
|
72
|
+
### Architecture Graphs (`.engineering-intelligence/graph/`)
|
|
73
|
+
|
|
74
|
+
| Artifact | Content |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `dependency-graph.json` | Module/package dependency relationships |
|
|
77
|
+
| `service-graph.json` | Service-to-service communication topology |
|
|
78
|
+
| `runtime-graph.json` | Runtime call flows and middleware chains |
|
|
79
|
+
| `business-flow-graph.json` | Business process flows across system boundaries |
|
|
80
|
+
| `architecture-map.md` | Mermaid diagrams derived from JSON graphs |
|
|
81
|
+
|
|
82
|
+
### Change History
|
|
83
|
+
|
|
84
|
+
| Artifact | Content |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `.changes/CHG-000-initialization.md` | Record of this initialization run |
|
|
87
|
+
|
|
88
|
+
## Procedure
|
|
89
|
+
|
|
90
|
+
1. **Discover** — Scan for: package manifests, workspace configs, runtimes (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, etc.), build systems, entrypoints, CI configs, Dockerfiles, deployment manifests, environment examples, database schemas/migrations, API definitions, auth configs, test suites.
|
|
91
|
+
|
|
92
|
+
2. **Trace Architecture** — Follow imports, dependency injection, middleware registration, route definitions, event handlers, and service boundaries. Map the critical runtime flows from code evidence, not assumptions.
|
|
93
|
+
|
|
94
|
+
3. **Write Knowledge Base** — For each document:
|
|
95
|
+
- Open with a one-paragraph summary
|
|
96
|
+
- Back every material claim with a file path reference: `(evidence: path/to/file:L42)`
|
|
97
|
+
- Use `**Not detected**` for absent features, not silence
|
|
98
|
+
- Use `**Unclear from evidence** — [reason]` for ambiguous areas
|
|
99
|
+
- Use tables, code blocks, and structured lists — never prose walls
|
|
100
|
+
|
|
101
|
+
4. **Validate Claims** — Re-read each knowledge document, check major claims against actual files, and write `15-validation-report.md` with findings categorized as: ✅ Supported, ⚠️ Partially Supported, ❌ Unsupported, ❓ Needs Human Review.
|
|
102
|
+
|
|
103
|
+
5. **Generate Memory** — Extract only durable, long-lived decisions and patterns. Do NOT store transient implementation details. Each entry needs a `Source:` evidence reference.
|
|
104
|
+
|
|
105
|
+
6. **Generate Context** — Create concise, navigational maps. Each map should fit in ~100 lines. Optimize for an AI agent quickly finding the right file, not for human reading.
|
|
106
|
+
|
|
107
|
+
7. **Build Graphs** — Invoke `graph-engine` to produce all four JSON graphs and `architecture-map.md`. Every node and edge must have `evidence` and `confidence` fields.
|
|
108
|
+
|
|
109
|
+
8. **Generate Events** — Write change-event guidance documents that describe what to check and update when specific types of changes occur.
|
|
110
|
+
|
|
111
|
+
9. **Write History** — Create `CHG-000-initialization.md` with: timestamp, artifacts generated, confidence summary, areas needing human confirmation.
|
|
112
|
+
|
|
113
|
+
10. **Report** — Summarize: total artifacts created, evidence coverage percentage estimate, high-confidence vs low-confidence areas, explicit list of items requiring human review.
|
|
114
|
+
|
|
115
|
+
## Quality Gates
|
|
116
|
+
|
|
117
|
+
- [ ] Every knowledge document has at least one evidence citation
|
|
118
|
+
- [ ] No document contains invented implementation details
|
|
119
|
+
- [ ] Validation report exists and covers all knowledge documents
|
|
120
|
+
- [ ] All four graph JSON files validate against the graph-engine schema
|
|
121
|
+
- [ ] Memory contains only durable, long-lived knowledge
|
|
122
|
+
- [ ] Context maps are concise (< 150 lines each)
|
|
123
|
+
- [ ] CHG-000 record exists and lists all generated artifacts
|
|
124
|
+
|
|
125
|
+
## Cross-References
|
|
126
|
+
|
|
127
|
+
- Uses: `deep-project-knowledge-extractor`, `knowledge-base-validator`, `graph-engine`, `change-history-engine`
|
|
128
|
+
- Consumed by: `engineering-intelligence-skill`, all sync engines, `impact-analysis-engine`
|
|
129
|
+
|
|
130
|
+
This initialization documents and validates the project. It does not implement product changes.
|
|
@@ -1,17 +1,102 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: knowledge-base-validator
|
|
3
3
|
description: Validates project knowledge documentation against source and configuration evidence, identifying stale, unsupported, or uncertain claims. Use after initialization or documentation synchronization.
|
|
4
|
+
version: 3.0.0
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Knowledge Base Validator
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Systematically audit every significant claim in `knowledge-base/*.md` against actual repository evidence. Produce a structured validation report that identifies exactly what is supported, what is stale, and what needs human review.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
## Inputs
|
|
11
12
|
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
- confidence and stale-documentation risks
|
|
15
|
-
- areas needing human review
|
|
13
|
+
- Repository root path with `knowledge-base/` present
|
|
14
|
+
- Optional: specific documents to validate (defaults to all)
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
## Procedure
|
|
17
|
+
|
|
18
|
+
1. **Enumerate Claims** — Read each `knowledge-base/*.md` document. Extract every material claim about architecture, APIs, schemas, dependencies, configurations, flows, and behavior.
|
|
19
|
+
|
|
20
|
+
2. **Verify Against Evidence** — For each claim, check:
|
|
21
|
+
- Does the referenced file/path still exist?
|
|
22
|
+
- Does the code at that location still support the claim?
|
|
23
|
+
- Has the relevant code changed since the claim was written?
|
|
24
|
+
- Are there new files/patterns that contradict the claim?
|
|
25
|
+
|
|
26
|
+
3. **Categorize Findings** — Assign each finding a status:
|
|
27
|
+
|
|
28
|
+
| Status | Symbol | Meaning |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| Supported | ✅ | Claim verified against current code |
|
|
31
|
+
| Partially Supported | ⚠️ | Claim is partly true but missing nuance or outdated in some aspect |
|
|
32
|
+
| Unsupported | ❌ | Claim contradicted by current code or evidence is missing |
|
|
33
|
+
| Unclear | ❓ | Cannot determine accuracy — needs human review |
|
|
34
|
+
| Stale | 🔄 | Claim references code that has changed significantly |
|
|
35
|
+
|
|
36
|
+
4. **Assess Confidence** — For each document, calculate:
|
|
37
|
+
- Total claims examined
|
|
38
|
+
- Distribution across statuses
|
|
39
|
+
- Overall document confidence: High (>90% ✅), Medium (70-90% ✅), Low (<70% ✅)
|
|
40
|
+
|
|
41
|
+
5. **Write Report** — Generate `knowledge-base/15-validation-report.md`
|
|
42
|
+
|
|
43
|
+
## Output Format
|
|
44
|
+
|
|
45
|
+
```markdown
|
|
46
|
+
# Validation Report
|
|
47
|
+
|
|
48
|
+
Generated: <ISO timestamp>
|
|
49
|
+
Scope: <documents validated>
|
|
50
|
+
|
|
51
|
+
## Summary
|
|
52
|
+
|
|
53
|
+
| Document | Claims | ✅ | ⚠️ | ❌ | ❓ | Confidence |
|
|
54
|
+
|---|---|---|---|---|---|---|
|
|
55
|
+
| 00-project-overview.md | 12 | 10 | 1 | 0 | 1 | High |
|
|
56
|
+
| ... | ... | ... | ... | ... | ... | ... |
|
|
57
|
+
|
|
58
|
+
## Detailed Findings
|
|
59
|
+
|
|
60
|
+
### 00-project-overview.md
|
|
61
|
+
|
|
62
|
+
#### ✅ Supported
|
|
63
|
+
- "Uses Express.js 4.18" (evidence: package.json:L15)
|
|
64
|
+
|
|
65
|
+
#### ⚠️ Partially Supported
|
|
66
|
+
- "PostgreSQL is the primary database" — true, but Redis is also used for caching (evidence: docker-compose.yml:L22)
|
|
67
|
+
|
|
68
|
+
#### ❌ Unsupported
|
|
69
|
+
- "Uses Passport.js for auth" — no Passport dependency found; appears to use custom JWT middleware (evidence: package.json, src/middleware/auth.ts)
|
|
70
|
+
|
|
71
|
+
#### ❓ Needs Human Review
|
|
72
|
+
- "Supports multi-tenancy" — tenant isolation code exists but completeness is unclear
|
|
73
|
+
|
|
74
|
+
## Stale Documentation Risks
|
|
75
|
+
|
|
76
|
+
- <areas where code has diverged from docs>
|
|
77
|
+
|
|
78
|
+
## Recommended Actions
|
|
79
|
+
|
|
80
|
+
- <specific documents needing update>
|
|
81
|
+
- <claims needing human confirmation>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Rules
|
|
85
|
+
|
|
86
|
+
- Do NOT silently rewrite knowledge documents during validation
|
|
87
|
+
- Update knowledge documents only as part of an explicit synchronization workflow
|
|
88
|
+
- Report honestly — a low-confidence score is valuable information
|
|
89
|
+
- Flag areas where you lack sufficient context to validate
|
|
90
|
+
|
|
91
|
+
## Quality Gates
|
|
92
|
+
|
|
93
|
+
- [ ] Every knowledge document (00-14) is covered in the report
|
|
94
|
+
- [ ] Each finding has an evidence path or explicit "no evidence found"
|
|
95
|
+
- [ ] Summary table has accurate counts
|
|
96
|
+
- [ ] Stale documentation risks are identified
|
|
97
|
+
- [ ] Recommended actions are actionable
|
|
98
|
+
|
|
99
|
+
## Cross-References
|
|
100
|
+
|
|
101
|
+
- Used by: `initialize-intelligence-skill`, `incremental-sync-engine`
|
|
102
|
+
- Depends on: `deep-project-knowledge-extractor` (produces the docs to validate)
|
|
@@ -1,17 +1,86 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: knowledge-sync-engine
|
|
3
3
|
description: Incrementally synchronizes the project knowledge base after code changes, updating only documents affected by verified behavior changes. Use after implementation or architectural decisions.
|
|
4
|
+
version: 3.0.0
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Knowledge Synchronization
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Update only the knowledge-base documents affected by a verified behavior change. Preserve accurate existing content — never regenerate entire documents.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
- persistence/schema: `knowledge-base/05-database.md`
|
|
12
|
-
- authentication/authorization: `knowledge-base/06-authentication.md`
|
|
13
|
-
- runtime flow: `knowledge-base/03-runtime-flow.md`
|
|
14
|
-
- architecture: `knowledge-base/02-architecture.md`
|
|
15
|
-
- frontend/backend/infrastructure/integrations: corresponding knowledge documents
|
|
11
|
+
## Inputs
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
- Persisted impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
|
|
14
|
+
- Actual diff or change record showing what changed
|
|
15
|
+
- Current `knowledge-base/` documents
|
|
16
|
+
|
|
17
|
+
## Document-to-Change Mapping
|
|
18
|
+
|
|
19
|
+
| Change Category | Primary Document | Also Check |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| API routes, endpoints, payloads | `04-api-documentation.md` | `03-runtime-flow.md` |
|
|
22
|
+
| Database schema, migrations | `05-database.md` | `02-architecture.md` |
|
|
23
|
+
| Auth flows, permissions | `06-authentication.md` | `03-runtime-flow.md`, `11-complex-areas.md` |
|
|
24
|
+
| Frontend components, routing | `07-frontend.md` | `01-repository-structure.md` |
|
|
25
|
+
| Backend services, middleware | `08-backend.md` | `03-runtime-flow.md` |
|
|
26
|
+
| CI/CD, deployment, hosting | `09-infrastructure.md` | — |
|
|
27
|
+
| Third-party integrations | `10-integrations.md` | `01-repository-structure.md` |
|
|
28
|
+
| New complex logic | `11-complex-areas.md` | — |
|
|
29
|
+
| Debt introduced or resolved | `12-technical-debt.md` | — |
|
|
30
|
+
| Dev workflow changes | `13-onboarding.md` | — |
|
|
31
|
+
| New domain terms | `14-glossary.md` | — |
|
|
32
|
+
| Architecture changes | `02-architecture.md` | `01-repository-structure.md`, `03-runtime-flow.md` |
|
|
33
|
+
| New packages or modules | `01-repository-structure.md` | `02-architecture.md` |
|
|
34
|
+
| Project overview changes | `00-project-overview.md` | — |
|
|
35
|
+
|
|
36
|
+
## Procedure
|
|
37
|
+
|
|
38
|
+
1. **Read Impact Report** — Identify which knowledge documents are flagged as affected.
|
|
39
|
+
|
|
40
|
+
2. **Read Affected Documents** — Load only the documents identified in step 1.
|
|
41
|
+
|
|
42
|
+
3. **Identify Stale Sections** — For each affected document, find the specific sections that reference changed code, APIs, schemas, or behavior.
|
|
43
|
+
|
|
44
|
+
4. **Update Sections** — For each stale section:
|
|
45
|
+
- Rewrite with current, accurate information
|
|
46
|
+
- Add evidence citations: `(evidence: path/to/file:L42)`
|
|
47
|
+
- Mark uncertain areas: `**Unclear from evidence** — [reason]`
|
|
48
|
+
- Preserve all unaffected content exactly as-is
|
|
49
|
+
|
|
50
|
+
5. **Verify Consistency** — Check that updated sections don't contradict other sections in the same document or other knowledge documents.
|
|
51
|
+
|
|
52
|
+
## Evidence Attachment Format
|
|
53
|
+
|
|
54
|
+
Every changed claim must include an evidence citation:
|
|
55
|
+
|
|
56
|
+
```markdown
|
|
57
|
+
The auth middleware now validates JWT tokens using RS256 algorithm
|
|
58
|
+
(evidence: src/middleware/auth.ts:L15-L28)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
For removed features:
|
|
62
|
+
```markdown
|
|
63
|
+
~~OAuth2 PKCE flow support~~ — Removed in CHG-015
|
|
64
|
+
(evidence: git diff, src/auth/oauth.ts deleted)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Rules
|
|
68
|
+
|
|
69
|
+
- Update only documents and sections identified by the impact report
|
|
70
|
+
- Preserve all accurate existing content unchanged
|
|
71
|
+
- Attach evidence for every changed claim
|
|
72
|
+
- Never regenerate entire documents during incremental sync
|
|
73
|
+
- If unsure whether a claim is stale, flag it rather than silently rewriting
|
|
74
|
+
|
|
75
|
+
## Quality Gates
|
|
76
|
+
|
|
77
|
+
- [ ] Only impact-identified documents were modified
|
|
78
|
+
- [ ] Changed sections have evidence citations
|
|
79
|
+
- [ ] Accurate existing content was preserved
|
|
80
|
+
- [ ] No documents were fully regenerated
|
|
81
|
+
|
|
82
|
+
## Cross-References
|
|
83
|
+
|
|
84
|
+
- Depends on: `impact-analysis-engine` (identifies affected documents)
|
|
85
|
+
- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
|
|
86
|
+
- Related: `knowledge-base-validator` (validates after sync)
|
|
@@ -1,18 +1,80 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: memory-sync-engine
|
|
3
3
|
description: Maintains durable engineering memory after architecture, business rule, constraint, convention, or technology decisions change. Use only for long-lived knowledge.
|
|
4
|
+
version: 3.0.0
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Memory Synchronization
|
|
7
8
|
|
|
8
|
-
Maintain
|
|
9
|
+
Maintain durable, long-lived engineering memory. Memory is for decisions and patterns that persist across many changes — never for transient implementation details.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
- `business-rules.md`
|
|
12
|
-
- `coding-patterns.md`
|
|
13
|
-
- `project-constraints.md`
|
|
14
|
-
- `technology-decisions.md`
|
|
11
|
+
## Inputs
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
- Impact report and actual change evidence
|
|
14
|
+
- Current `.engineering-intelligence/memory/` documents
|
|
17
15
|
|
|
18
|
-
|
|
16
|
+
## Memory Categories
|
|
17
|
+
|
|
18
|
+
| Document | Content | Update Trigger |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `architecture-decisions.md` | ADRs, layer definitions, boundary rules, communication patterns | Architecture changes, new service boundaries, pattern adoptions |
|
|
21
|
+
| `business-rules.md` | Domain invariants, validation rules, business logic constraints | Business logic changes, regulatory updates |
|
|
22
|
+
| `coding-patterns.md` | Recurring conventions, idioms, naming rules, file organization | Refactors that establish new patterns, convention changes |
|
|
23
|
+
| `project-constraints.md` | Performance budgets, compatibility requirements, SLA targets, regulatory | Infrastructure changes, new compliance requirements |
|
|
24
|
+
| `technology-decisions.md` | Stack choices, framework versions, deprecation timelines, migration plans | Dependency updates, technology migrations |
|
|
25
|
+
|
|
26
|
+
## Staleness Detection Rules
|
|
27
|
+
|
|
28
|
+
A memory entry may be stale if:
|
|
29
|
+
|
|
30
|
+
1. **Referenced code no longer exists** — The decision references files/modules that were deleted or renamed
|
|
31
|
+
2. **Contradicted by current code** — The pattern described is no longer followed in the codebase
|
|
32
|
+
3. **Superseded by new decision** — A newer decision overrides the documented one
|
|
33
|
+
4. **Evidence outdated** — The evidence citations point to significantly changed code
|
|
34
|
+
|
|
35
|
+
## Procedure
|
|
36
|
+
|
|
37
|
+
1. **Check Trigger** — Review the impact report. Does the change affect a durable decision, rule, constraint, pattern, or technology choice? If not, **stop — leave memory unchanged**.
|
|
38
|
+
|
|
39
|
+
2. **Identify Affected Entries** — Match the change against memory categories above. Only proceed for matching categories.
|
|
40
|
+
|
|
41
|
+
3. **Update Entry** — For each affected entry:
|
|
42
|
+
```markdown
|
|
43
|
+
## <Decision/Pattern Title>
|
|
44
|
+
|
|
45
|
+
**Status**: Active | Superseded | Deprecated
|
|
46
|
+
**Decided**: <date or CHG reference>
|
|
47
|
+
**Last verified**: <date>
|
|
48
|
+
|
|
49
|
+
<Description of the decision/pattern>
|
|
50
|
+
|
|
51
|
+
**Rationale**: <why this was chosen>
|
|
52
|
+
**Source**: (evidence: path/to/file)
|
|
53
|
+
**Alternatives considered**: <if applicable>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
4. **Verify Durability** — Before adding a new memory entry, confirm it's truly durable:
|
|
57
|
+
- Will this still be relevant after 5+ more changes?
|
|
58
|
+
- Is this a decision or just an implementation detail?
|
|
59
|
+
- Is this captured better elsewhere (knowledge-base, context)?
|
|
60
|
+
|
|
61
|
+
## Rules
|
|
62
|
+
|
|
63
|
+
- **Durable only**: Do not store transient implementation notes or unverified assumptions
|
|
64
|
+
- **Evidence required**: Every entry must cite source evidence
|
|
65
|
+
- **Leave unchanged when appropriate**: Most changes do NOT affect durable memory — it's correct to update nothing
|
|
66
|
+
- **Status tracking**: Mark superseded decisions as `Superseded` rather than deleting them — history matters
|
|
67
|
+
- **No product code**: Memory synchronization never modifies product code
|
|
68
|
+
|
|
69
|
+
## Quality Gates
|
|
70
|
+
|
|
71
|
+
- [ ] Change was verified to affect durable knowledge before updating
|
|
72
|
+
- [ ] Only affected entries were modified
|
|
73
|
+
- [ ] New entries are truly durable (not transient implementation details)
|
|
74
|
+
- [ ] All entries have evidence citations
|
|
75
|
+
- [ ] Superseded entries are marked, not deleted
|
|
76
|
+
|
|
77
|
+
## Cross-References
|
|
78
|
+
|
|
79
|
+
- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
|
|
80
|
+
- Consumed by: `engineering-orchestrator` (for routing decisions), `change-agent` (for pattern compliance)
|
|
@@ -1,10 +1,151 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: refactoring-planner
|
|
3
3
|
description: Plans safe refactors by identifying dependencies, migration steps, validation needs, compatibility risk, and rollback strategy. Use before non-trivial refactors.
|
|
4
|
+
version: 3.0.0
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
# Refactoring Planner
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Plan safe, incremental refactoring with clear migration steps, validation checkpoints, and rollback strategies.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
## Inputs
|
|
12
|
+
|
|
13
|
+
- Refactoring goal (described by user or identified by architecture review)
|
|
14
|
+
- `.engineering-intelligence/graph/` (dependency relationships)
|
|
15
|
+
- `knowledge-base/12-technical-debt.md` (existing debt)
|
|
16
|
+
- `.engineering-intelligence/memory/architecture-decisions.md` (constraints)
|
|
17
|
+
|
|
18
|
+
## Refactoring Categories
|
|
19
|
+
|
|
20
|
+
| Category | Examples | Risk Level |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| **Extract** | Extract module, service, function, interface | Medium |
|
|
23
|
+
| **Rename** | Rename module, restructure directories | Low–Medium |
|
|
24
|
+
| **Consolidate** | Merge duplicate logic, unify patterns | Medium |
|
|
25
|
+
| **Decouple** | Break circular deps, introduce interfaces | Medium–High |
|
|
26
|
+
| **Migrate** | Change framework, database, language version | High |
|
|
27
|
+
| **Restructure** | Redefine boundaries, change architecture pattern | High–Critical |
|
|
28
|
+
|
|
29
|
+
## Risk Scoring
|
|
30
|
+
|
|
31
|
+
| Factor | Low (1) | Medium (2) | High (3) | Critical (4) |
|
|
32
|
+
|---|---|---|---|---|
|
|
33
|
+
| **Scope** | 1–3 files | 4–10 files | 10–25 files | 25+ files |
|
|
34
|
+
| **Dependents** | 0–2 consumers | 3–5 consumers | 6–10 consumers | 10+ consumers |
|
|
35
|
+
| **Test coverage** | Well-tested | Partial | Sparse | None |
|
|
36
|
+
| **Data impact** | None | Read-only paths | Write paths | Schema changes |
|
|
37
|
+
| **Rollback** | Git revert | Multi-step | Complex | Irreversible |
|
|
38
|
+
|
|
39
|
+
**Overall Risk** = max(all factors). If any factor is Critical, the refactor is Critical.
|
|
40
|
+
|
|
41
|
+
## Procedure
|
|
42
|
+
|
|
43
|
+
1. **Analyze Current State** — Using graphs and knowledge base:
|
|
44
|
+
- Map the exact scope of the refactor
|
|
45
|
+
- Identify all dependents of the code to be changed
|
|
46
|
+
- Note test coverage for affected areas
|
|
47
|
+
- Check for related technical debt
|
|
48
|
+
|
|
49
|
+
2. **Design Target State** — Define:
|
|
50
|
+
- What the code should look like after refactoring
|
|
51
|
+
- New module/file structure (if changing boundaries)
|
|
52
|
+
- New interfaces or abstractions (if decoupling)
|
|
53
|
+
- Migration strategy for data (if applicable)
|
|
54
|
+
|
|
55
|
+
3. **Plan Migration Steps** — Break into incremental, independently-deployable steps:
|
|
56
|
+
```markdown
|
|
57
|
+
### Step 1: <name>
|
|
58
|
+
- Changes: <what to modify>
|
|
59
|
+
- Validation: <how to verify this step>
|
|
60
|
+
- Rollback: <how to revert just this step>
|
|
61
|
+
- Dependencies: <what must be done first>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
4. **Identify Validation Needs** — For each step:
|
|
65
|
+
- Existing tests that must pass
|
|
66
|
+
- New tests to add before refactoring
|
|
67
|
+
- Integration tests to verify behavior preservation
|
|
68
|
+
- Performance benchmarks (if applicable)
|
|
69
|
+
|
|
70
|
+
5. **Define Rollback Strategy** — For the overall refactor:
|
|
71
|
+
- Can it be reverted with `git revert`?
|
|
72
|
+
- Are there data migrations that need reverse migrations?
|
|
73
|
+
- What's the point of no return?
|
|
74
|
+
|
|
75
|
+
6. **Write Plan** — Generate `knowledge-base/18-refactor-plan.md`
|
|
76
|
+
|
|
77
|
+
## Output Format
|
|
78
|
+
|
|
79
|
+
```markdown
|
|
80
|
+
# Refactoring Plan: <title>
|
|
81
|
+
|
|
82
|
+
## Motivation
|
|
83
|
+
<Why this refactor is needed — link to technical debt or architecture review>
|
|
84
|
+
|
|
85
|
+
## Current State
|
|
86
|
+
<What exists now, with file paths>
|
|
87
|
+
|
|
88
|
+
## Target State
|
|
89
|
+
<What should exist after, with proposed structure>
|
|
90
|
+
|
|
91
|
+
## Risk Assessment
|
|
92
|
+
| Factor | Rating | Justification |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| Scope | Medium | 8 files affected |
|
|
95
|
+
| Dependents | High | 7 modules import the target |
|
|
96
|
+
|
|
97
|
+
Overall Risk: **High**
|
|
98
|
+
|
|
99
|
+
## Migration Steps
|
|
100
|
+
|
|
101
|
+
### Step 1: Add new interface
|
|
102
|
+
- Files: src/interfaces/auth.ts (new)
|
|
103
|
+
- Validation: Type check passes
|
|
104
|
+
- Rollback: Delete the file
|
|
105
|
+
|
|
106
|
+
### Step 2: Implement adapter
|
|
107
|
+
- Files: src/auth/adapter.ts (new)
|
|
108
|
+
- Validation: Unit tests pass
|
|
109
|
+
- Rollback: Delete the file, revert imports
|
|
110
|
+
|
|
111
|
+
### Step 3: Migrate consumers (batch 1)
|
|
112
|
+
- Files: src/routes/users.ts, src/routes/admin.ts
|
|
113
|
+
- Validation: Integration tests pass
|
|
114
|
+
- Rollback: Revert consumer changes
|
|
115
|
+
|
|
116
|
+
## Validation Plan
|
|
117
|
+
- [ ] All existing tests pass after each step
|
|
118
|
+
- [ ] New tests added before behavior-preserving changes
|
|
119
|
+
- [ ] Integration suite green after full migration
|
|
120
|
+
|
|
121
|
+
## Rollback Strategy
|
|
122
|
+
- Steps 1-3 are independently revertible via git
|
|
123
|
+
- No data migrations required
|
|
124
|
+
- Point of no return: None — fully reversible
|
|
125
|
+
|
|
126
|
+
## Timeline Estimate
|
|
127
|
+
- Step 1: ~30 minutes
|
|
128
|
+
- Step 2: ~1 hour
|
|
129
|
+
- Step 3: ~2 hours
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Rules
|
|
133
|
+
|
|
134
|
+
- Never plan a refactor as a single big-bang change — break into steps
|
|
135
|
+
- Each step must be independently verifiable
|
|
136
|
+
- Add tests BEFORE making behavior-preserving changes
|
|
137
|
+
- Consider backward compatibility during migration
|
|
138
|
+
- This planning skill does not implement the refactor — it plans it
|
|
139
|
+
|
|
140
|
+
## Quality Gates
|
|
141
|
+
|
|
142
|
+
- [ ] All dependents are identified (not just direct consumers)
|
|
143
|
+
- [ ] Each step has a validation and rollback strategy
|
|
144
|
+
- [ ] Risk is scored with justification
|
|
145
|
+
- [ ] Migration steps are ordered by dependency
|
|
146
|
+
|
|
147
|
+
## Cross-References
|
|
148
|
+
|
|
149
|
+
- Depends on: `graph-engine` (dependency data), `architecture-review-engine` (findings)
|
|
150
|
+
- Used by: `engineering-intelligence-skill` (for refactor-type requests)
|
|
151
|
+
- Triggers: `impact-analysis-engine` (when the refactor is implemented)
|