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.
Files changed (44) hide show
  1. package/README.md +5 -1
  2. package/dist/adapters/index.js +3 -3
  3. package/dist/adapters/index.js.map +1 -1
  4. package/dist/cli/index.js +24 -3
  5. package/dist/cli/index.js.map +1 -1
  6. package/dist/templates.d.ts +1 -1
  7. package/dist/templates.js +2 -2
  8. package/dist/templates.js.map +1 -1
  9. package/dist/validation/index.js +1 -1
  10. package/dist/validation/index.js.map +1 -1
  11. package/dist/visualizer/index.d.ts +2 -0
  12. package/dist/visualizer/index.d.ts.map +1 -0
  13. package/dist/visualizer/index.js +599 -0
  14. package/dist/visualizer/index.js.map +1 -0
  15. package/package.json +3 -3
  16. package/templates/canonical/agents/change-agent.md +58 -1
  17. package/templates/canonical/agents/engineering-orchestrator.md +69 -3
  18. package/templates/canonical/agents/knowledge-agent.md +59 -2
  19. package/templates/canonical/agents/quality-agent.md +59 -2
  20. package/templates/canonical/rules/engineering-intelligence.md +42 -13
  21. package/templates/canonical/skills/architecture-review-engine/SKILL.md +112 -3
  22. package/templates/canonical/skills/change-detection-engine/SKILL.md +82 -7
  23. package/templates/canonical/skills/change-history-engine/SKILL.md +125 -5
  24. package/templates/canonical/skills/context-sync-engine/SKILL.md +116 -9
  25. package/templates/canonical/skills/deep-project-knowledge-extractor/SKILL.md +171 -5
  26. package/templates/canonical/skills/engineering-change-review/SKILL.md +145 -9
  27. package/templates/canonical/skills/engineering-intelligence-skill/SKILL.md +168 -0
  28. package/templates/canonical/skills/graph-engine/SKILL.md +134 -14
  29. package/templates/canonical/skills/impact-analysis-engine/SKILL.md +125 -11
  30. package/templates/canonical/skills/incremental-sync-engine/SKILL.md +75 -10
  31. package/templates/canonical/skills/initialize-intelligence-skill/SKILL.md +130 -0
  32. package/templates/canonical/skills/knowledge-base-validator/SKILL.md +92 -7
  33. package/templates/canonical/skills/knowledge-sync-engine/SKILL.md +77 -8
  34. package/templates/canonical/skills/memory-sync-engine/SKILL.md +70 -8
  35. package/templates/canonical/skills/refactoring-planner/SKILL.md +143 -2
  36. package/templates/canonical/skills/testing-intelligence-engine/SKILL.md +119 -3
  37. package/templates/canonical/workflows/analyze-impact.md +25 -3
  38. package/templates/canonical/workflows/engineering-intelligence.md +20 -3
  39. package/templates/canonical/workflows/initialize-engineering-intelligence.md +30 -3
  40. package/templates/canonical/workflows/map-architecture.md +17 -6
  41. package/templates/canonical/workflows/review-engineering-change.md +26 -2
  42. package/templates/canonical/workflows/sync-engineering-intelligence.md +20 -2
  43. package/templates/canonical/skills/engineering-intelligence/SKILL.md +0 -21
  44. 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
- Read `knowledge-base/*.md`, identify significant claims, and verify them against code, config, infrastructure, and tests.
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
- Write `knowledge-base/15-validation-report.md` with:
11
+ ## Inputs
11
12
 
12
- - supported, partially supported, unsupported, and unclear findings
13
- - evidence paths
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
- Do not silently rewrite other knowledge documents; update them only as part of an explicit synchronization workflow.
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
- Use the persisted impact report and actual diff to update only affected documents:
9
+ Update only the knowledge-base documents affected by a verified behavior change. Preserve accurate existing content — never regenerate entire documents.
9
10
 
10
- - API behavior: `knowledge-base/04-api-documentation.md`
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
- Preserve accurate existing detail and attach evidence for changed claims.
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 `.engineering-intelligence/memory/`:
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
- - `architecture-decisions.md`
11
- - `business-rules.md`
12
- - `coding-patterns.md`
13
- - `project-constraints.md`
14
- - `technology-decisions.md`
11
+ ## Inputs
15
12
 
16
- Do not store transient implementation notes or unverified assumptions as durable memory.
13
+ - Impact report and actual change evidence
14
+ - Current `.engineering-intelligence/memory/` documents
17
15
 
18
- Use the associated impact report and actual change evidence to decide whether durable memory is affected. Leave memory unchanged when no long-lived decision, rule, constraint, pattern, or technology choice changed.
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
- Identify duplicated logic, unsafe coupling, large or fragile areas, migration boundaries, and tests required to preserve behavior.
9
+ Plan safe, incremental refactoring with clear migration steps, validation checkpoints, and rollback strategies.
9
10
 
10
- For significant proposals, write `knowledge-base/18-refactor-plan.md` with motivation, affected areas, migration steps, risk controls, validation, and rollback guidance.
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)