🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
pi-agent-codebase-workflows
Advanced tools
pi-agent-codebase-workflows - npm Package Compare versions
| # Troubleshooting | ||
| ## No docs were created | ||
| Check that the prompt used a reconstruction command: | ||
| ```text | ||
| /recon-01-inventory | ||
| /recon-02-architecture | ||
| /recon-all | ||
| ``` | ||
| Reconstruction must not edit production code, but it should write `docs/agent/*.md` or scoped docs under `docs/agent/scopes/**`. | ||
| If the repo is large, prefer numbered passes over `/recon-all`. | ||
| ## Agent wrote scoped findings into top-level docs | ||
| Expected behavior: | ||
| - no focus argument -> top-level `docs/agent/*.md` | ||
| - focus argument -> `docs/agent/scopes/by-path/<focus>/...` or `docs/agent/scopes/by-domain/<slug>/...` | ||
| Fix: | ||
| 1. Move or summarize misplaced details into the correct scoped artifact. | ||
| 2. Update `docs/agent/SCOPES.md`. | ||
| 3. Run `/recon-08-consolidate` later if top-level summaries need reconciliation. | ||
| ## `SCOPES.md` missing or stale | ||
| `docs/agent/SCOPES.md` is created when first scoped pass runs. It may not exist in purely unscoped or legacy repos. | ||
| If scoped docs exist but `SCOPES.md` is missing: | ||
| - create/update `docs/agent/SCOPES.md` | ||
| - list each scope, docs path, status, ownership, and external contracts | ||
| If stale: | ||
| - mark outdated scopes as `stale` or `deprecated` | ||
| - update evidence paths and status during next scoped pass or consolidation | ||
| ## Scope path was renamed | ||
| Scoped path docs can become historical after source moves. | ||
| Fix: | ||
| 1. Verify whether the source path still exists. | ||
| 2. If moved, update `SCOPES.md` with new path and status. | ||
| 3. Treat old scoped docs as historical until revalidated against source. | ||
| 4. Re-run relevant scoped pass for the new path. | ||
| ## Too many scoped directories | ||
| Avoid creating a scope for every folder. | ||
| Prefer scopes for: | ||
| - packages | ||
| - apps | ||
| - services | ||
| - bounded domains | ||
| - major modules with separate ownership or contracts | ||
| Consolidate or deprecate tiny scopes in `SCOPES.md` when they add noise. | ||
| ## Agent read too many files | ||
| For large repos, provide explicit focus: | ||
| ```text | ||
| /recon-02-architecture packages/api | ||
| /preflight fix token refresh in packages/api | ||
| /review-arch packages/api | ||
| ``` | ||
| Scoped workflows should inspect focused area plus immediate dependencies, tests, entry points, and external boundaries only. | ||
| If investigation expands too broadly, stop and narrow target path/domain. | ||
| ## Cross-scope contract ownership unclear | ||
| Use `CONTRACTS.md`. | ||
| Rules: | ||
| - one owner scope per contract | ||
| - owner documents source of truth, compatibility rules, tests, and consumers | ||
| - consumers link to owner contract and document local usage/risk only | ||
| If ownership cannot be determined, record it as: | ||
| - known unknown | ||
| - drift risk | ||
| - follow-up item for consolidation | ||
| ## Top-level and scoped docs disagree | ||
| Do not silently delete disagreement evidence. | ||
| Fix: | ||
| 1. Check source evidence. | ||
| 2. Prefer latest verified source-backed observation. | ||
| 3. Keep scope-specific facts in scoped docs. | ||
| 4. Summarize stable repo-level guidance in top-level docs. | ||
| 5. Run `/recon-08-consolidate` to reconcile contradictions. | ||
| ## Existing legacy docs already exist | ||
| Legacy top-level docs remain valid. | ||
| Safe-change and review use top-level docs when `SCOPES.md` is absent. First focused recon pass adds scoped docs and `SCOPES.md` without deleting old docs. | ||
| Use consolidation when enough scoped material exists to update repo-level summaries. | ||
| ## Monorepo too large for `/recon-all` | ||
| Use numbered/scoped passes instead: | ||
| ```text | ||
| /recon-01-inventory | ||
| /recon-02-architecture packages/api | ||
| /recon-03-data-invariants packages/api | ||
| /recon-02-architecture apps/mobile | ||
| ``` | ||
| Keep each pass bounded. Let `/recon-08-consolidate` reconcile later. | ||
| ## Safe-change ignored scoped docs | ||
| Check: | ||
| - `docs/agent/SCOPES.md` exists | ||
| - target path is listed or covered by longest-prefix scope | ||
| - scoped source path still exists | ||
| - task wording includes relevant path/domain | ||
| Fix by providing explicit target: | ||
| ```text | ||
| /preflight fix billing total rounding in services/billing | ||
| ``` | ||
| ## Review missed a cross-module contract | ||
| Check whether touched API/type/schema/event is documented in scoped `CONTRACTS.md`. | ||
| If not: | ||
| 1. Identify owner scope. | ||
| 2. Add or update owner `CONTRACTS.md`. | ||
| 3. Link consumer scope to owner contract. | ||
| 4. Re-run `/review-arch` with explicit scope if needed. | ||
| ## Validation command unavailable | ||
| Use best available focused validation: | ||
| - targeted test for changed package/module | ||
| - type check for affected package | ||
| - lint for affected package | ||
| - build/smoke test for affected app/service | ||
| If no validation can run, report why and name the next best command for the user to run. |
+177
| # Tutorial | ||
| This package provides pi skills and prompt templates for reconstructing codebase knowledge, making safe changes, and reviewing architecture drift. | ||
| ## Install | ||
| From git: | ||
| ```bash | ||
| pi install git:github.com/PriNova/pi-agent-codebase-workflows | ||
| ``` | ||
| Local development/test: | ||
| ```bash | ||
| pi install /absolute/path/to/pi-agent-codebase-workflows | ||
| # or one-off | ||
| pi -e /absolute/path/to/pi-agent-codebase-workflows | ||
| ``` | ||
| ## Reconstruct a small repo | ||
| For small/simple repos, run all reconstruction passes: | ||
| ```text | ||
| /recon-all | ||
| ``` | ||
| This creates repo-level docs under: | ||
| ```text | ||
| docs/agent/ | ||
| ``` | ||
| and project operating guidance at: | ||
| ```text | ||
| AGENTS.md | ||
| ``` | ||
| ## Reconstruct a large repo or monorepo | ||
| Start with inventory: | ||
| ```text | ||
| /recon-01-inventory | ||
| ``` | ||
| Use the inventory's recommended targets for scoped passes: | ||
| ```text | ||
| /recon-02-architecture packages/api | ||
| /recon-03-data-invariants packages/api | ||
| /recon-04-dependency-rules packages/api | ||
| /recon-05-risk-register packages/api | ||
| /recon-02-architecture apps/mobile | ||
| /recon-03-data-invariants apps/mobile | ||
| ``` | ||
| Focused path passes write hierarchical scoped docs: | ||
| ```text | ||
| docs/agent/scopes/by-path/packages/api/ | ||
| README.md # optional local index for large/complex scopes | ||
| ARCHITECTURE.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| CONTRACTS.md | ||
| ``` | ||
| Focused domain passes write: | ||
| ```text | ||
| docs/agent/scopes/by-domain/auth-flow/ | ||
| ``` | ||
| `docs/agent/SCOPES.md` indexes scoped docs for later workflows. | ||
| ## Understand generated docs | ||
| Repo-level docs: | ||
| ```text | ||
| docs/agent/ARCHITECTURE.md | ||
| docs/agent/DATA_MODEL.md | ||
| docs/agent/INVARIANTS.md | ||
| docs/agent/DEPENDENCY_RULES.md | ||
| docs/agent/RISK_REGISTER.md | ||
| docs/agent/CHANGE_GUIDE.md | ||
| ``` | ||
| Use repo-level docs as summaries and fallback guidance. | ||
| Scoped docs: | ||
| ```text | ||
| docs/agent/scopes/by-path/<path>/... | ||
| docs/agent/scopes/by-domain/<slug>/... | ||
| ``` | ||
| Use scoped docs for package/module/service/domain-specific facts. | ||
| `CONTRACTS.md` documents cross-module APIs, shared types, schemas, events, generated clients, persistence boundaries, and ownership. | ||
| ## Make a safe change | ||
| Start with preflight: | ||
| ```text | ||
| /preflight fix login refresh bug in packages/api | ||
| ``` | ||
| For a bug: | ||
| ```text | ||
| /bug-diagnose fix login refresh bug in packages/api | ||
| /bug-implement approved plan | ||
| ``` | ||
| For a feature: | ||
| ```text | ||
| /feature-design add export endpoint to packages/api | ||
| /feature-implement approved plan | ||
| ``` | ||
| For a refactor: | ||
| ```text | ||
| /refactor-design split billing service adapter | ||
| /refactor-implement approved stage 1 | ||
| ``` | ||
| Safe-change reads `docs/agent/SCOPES.md` when present, matches path scopes by longest prefix, reads scoped docs first, then falls back to repo-level docs. | ||
| ## Review architecture | ||
| Review current diff: | ||
| ```text | ||
| /review-arch | ||
| ``` | ||
| Review with explicit focus: | ||
| ```text | ||
| /review-arch packages/api | ||
| ``` | ||
| Review checks architecture drift, data consistency, invariants, dependency direction, public contracts, side-effect boundaries, and tests. | ||
| ## Consolidate scoped findings | ||
| After several scoped passes, reconcile them: | ||
| ```text | ||
| /recon-08-consolidate | ||
| ``` | ||
| Consolidation keeps detailed facts in scoped docs and summarizes stable repo-level guidance into top-level docs. | ||
| ## Legacy reconstructed repos | ||
| Repos reconstructed before scoped artifacts still work. | ||
| If only top-level `docs/agent/*.md` exists: | ||
| - safe-change uses those docs | ||
| - review uses those docs | ||
| - a later focused recon pass creates `docs/agent/SCOPES.md` and scoped artifacts additively | ||
| - existing top-level docs are not deleted | ||
| Use consolidation later to reconcile old repo-level details with newer scoped docs. |
| # Bug Fix Workflow | ||
| Use for errors, regressions, failing behavior, or mismatches between expected and actual behavior. | ||
| ## Bug Diagnosis | ||
| After preflight, diagnose bug before editing. | ||
| Tasks: | ||
| 1. Reproduce or locate bug. | ||
| 2. Identify expected behavior. | ||
| 3. Identify violated invariant, contract, or public behavior. | ||
| 4. Identify affected files/modules. | ||
| 5. Explain likely root cause. | ||
| 6. Propose minimal fix plan. | ||
| 7. Propose regression test and validation commands. | ||
| Stop unless user approved implementation. | ||
| ## Bug Implementation | ||
| Continue from approved bug-fix plan. | ||
| Rules: | ||
| - Follow approved plan. | ||
| - Change production code only where necessary. | ||
| - Add/update regression test unless impossible; explain if impossible. | ||
| - Do not opportunistically refactor. | ||
| - Run focused test first, then relevant broader suite. | ||
| - Update `docs/agent/RISK_REGISTER.md` or scoped `RISK_REGISTER.md` if bug corresponds to known/new risk. | ||
| - Update `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/CHANGE_GUIDE.md`, or scoped equivalents only if fix clarifies/changes durable rules. | ||
| Output: | ||
| - Files changed | ||
| - Root cause fixed | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining risks/follow-up |
| # Semantic Docs Update Rules | ||
| Update docs only when durable semantics changed. | ||
| Update relevant top-level or scoped docs for changes to: | ||
| - architecture or dependency direction | ||
| - data model, persisted/serialized formats, schemas, API contracts, or shared types | ||
| - invariants, lifecycle rules, state transitions, validation, or ownership rules | ||
| - side-effect boundaries | ||
| - public/internal contracts between modules/packages/services | ||
| - known risks or risk status | ||
| - safe-change workflow guidance discovered during implementation | ||
| Do not update docs for: | ||
| - purely mechanical edits | ||
| - local implementation detail with no durable semantic meaning | ||
| - test-only changes that do not reveal changed risk/invariant guidance | ||
| - formatting, naming, or low-level cleanup without architecture impact | ||
| When scoped docs exist: | ||
| - update matched scoped docs first | ||
| - update owner `CONTRACTS.md` for contract changes | ||
| - update consumer docs only for local usage/risk changes | ||
| - update top-level docs only if repo-level summary/guidance changed | ||
| - leave broader reconciliation for codebase-recon Pass 8 when multiple scopes are affected |
| # Feature Workflow | ||
| Use for new behavior, API capability, UI behavior, data flow, integration, or user-facing functionality. | ||
| ## Feature Design | ||
| After preflight, design before implementation. | ||
| Tasks: | ||
| 1. Feature summary | ||
| 2. Affected user/execution flow | ||
| 3. Affected modules/files | ||
| 4. Data model impact | ||
| 5. Invariants affected or introduced | ||
| 6. Side effects needed and boundaries | ||
| 7. Dependency rule impact | ||
| 8. Risks | ||
| 9. Test plan | ||
| 10. Minimal implementation plan | ||
| 11. Documentation update plan | ||
| 12. Blocking open questions only | ||
| Rules: | ||
| - Prefer extending existing concepts over new abstractions. | ||
| - Keep side effects at existing side-effect boundaries. | ||
| - Do not introduce global/shared utilities unless justified. | ||
| - Stop unless user approved implementation. | ||
| ## Feature Implementation | ||
| Continue from approved feature design. | ||
| Rules: | ||
| - Follow approved design. | ||
| - Keep changes inside affected slice/module when possible. | ||
| - No unrelated refactoring. | ||
| - Add/update tests according to test plan. | ||
| - Preserve existing invariants. | ||
| - Keep side effects behind existing boundaries. | ||
| - Update docs only for durable semantic changes. | ||
| - Run focused tests, then broader validation. | ||
| Output: | ||
| - Files changed | ||
| - Feature behavior implemented | ||
| - Data model changes | ||
| - Invariants added/changed | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining risks/limitations |
| # Universal Preflight | ||
| Preflight comes before every non-trivial safe-change task. | ||
| Read first: | ||
| - `docs/agent/CHANGE_GUIDE.md` if present | ||
| - `docs/agent/SCOPES.md` if present; then apply `references/scoped-docs.md` | ||
| If scoped docs match the task, read nearest scoped `README.md` only if present and only task-relevant scoped docs first. Then read only missing or repo-wide top-level docs relevant to task: | ||
| - `docs/agent/ARCHITECTURE.md` or scoped `ARCHITECTURE.md` for module/flow changes | ||
| - `docs/agent/DATA_MODEL.md` or scoped `DATA_MODEL.md` for data changes | ||
| - `docs/agent/INVARIANTS.md` or scoped `INVARIANTS.md` for rule-sensitive changes | ||
| - `docs/agent/DEPENDENCY_RULES.md` or scoped `DEPENDENCY_RULES.md` for imports/module boundaries | ||
| - `docs/agent/RISK_REGISTER.md` or scoped `RISK_REGISTER.md` for risky areas | ||
| - `docs/agent/DESIGN_ISSUES.md` or scoped `DESIGN_ISSUES.md` for refactoring/design work | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
| Before editing code, produce: | ||
| 1. Task classification: bug fix / feature / refactoring / risk-fix / test-only / docs-only | ||
| 2. Relevant docs read | ||
| 3. Affected slice/module/user flow | ||
| 4. Expected files to inspect | ||
| 5. Invariants/contracts at risk | ||
| 6. Existing tests/validation commands | ||
| 7. Whether implementation should proceed now or wait for approval |
| # Refactoring Workflow | ||
| Use for behavior-preserving structure changes, design cleanup, decomposition, dependency direction cleanup, or reducing drift. Do not combine refactoring with feature work or unrelated bug fixes. | ||
| ## Refactoring Design | ||
| After preflight, design refactor before edits. | ||
| Rules: | ||
| - No behavior change. | ||
| - Treat refactoring as separate use case. | ||
| - Identify smell/design issue precisely with evidence. | ||
| - Identify tests protecting behavior. | ||
| - If tests insufficient, propose characterization tests first. | ||
| - Prefer staged refactorings over rewrites. | ||
| - Do not introduce new architecture style unless explicitly requested. | ||
| Output: | ||
| - Refactoring goal | ||
| - Current design problem | ||
| - Evidence | ||
| - Behavior to preserve | ||
| - Affected files/modules | ||
| - Invariants to preserve | ||
| - Required characterization tests | ||
| - Refactoring stages | ||
| - Validation plan | ||
| - Rollback strategy | ||
| - Documentation update plan | ||
| Stop unless user approved implementation. | ||
| ## Refactoring Implementation | ||
| Continue from approved refactoring design, one smallest safe stage. | ||
| Rules: | ||
| - Preserve behavior. | ||
| - Do not combine with feature work. | ||
| - Do not fix unrelated bugs unless they block refactor. | ||
| - Add characterization tests before behavior-sensitive changes. | ||
| - Keep each change mechanically understandable. | ||
| - Run tests after each meaningful stage. | ||
| - Update docs only if durable structure/dependency/change guidance changed. | ||
| Output: | ||
| - Stage completed | ||
| - Files changed | ||
| - Behavior preserved | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining stages |
| # Risk-Fix Workflow | ||
| Use when risk-derived tests fail or `RISK_REGISTER.md` / scoped `RISK_REGISTER.md` identifies actionable risks. | ||
| Read first: | ||
| - `docs/agent/CHANGE_GUIDE.md` | ||
| - `docs/agent/SCOPES.md` if present; then apply `references/scoped-docs.md` | ||
| - matching scoped risk/invariant/data docs when applicable | ||
| - `docs/agent/RISK_REGISTER.md` | ||
| - `docs/agent/INVARIANTS.md` | ||
| - `docs/agent/DATA_MODEL.md` | ||
| Rules: | ||
| - Do not fix all failing tests at once. | ||
| - Select one failing test or tightly related risk cluster. | ||
| - Prioritize: critical data corruption, security/safety, persistence/state inconsistency, public API/schema breakage, incorrect domain behavior, architecture boundary violation, performance/cleanup. | ||
| - Explain violated invariant. | ||
| - Identify minimal production-code change. | ||
| - Do not change test unless demonstrably wrong. | ||
| - Do not refactor unrelated code. | ||
| - Run focused test first, then surrounding suite. | ||
| - Update `docs/agent/RISK_REGISTER.md` or scoped `RISK_REGISTER.md` status. | ||
| Output: | ||
| - Selected failing test/risk cluster | ||
| - Root cause | ||
| - Invariant violated | ||
| - Minimal fix plan | ||
| - Files changed | ||
| - Validation result | ||
| - Remaining failing tests/risks |
| # Scoped Docs Discovery | ||
| Safe-change works with both legacy unscoped reconstruction docs and hierarchical scoped docs. | ||
| If `docs/agent/SCOPES.md` is absent: | ||
| - use the existing top-level `docs/agent/*.md` workflow only | ||
| If `docs/agent/SCOPES.md` is present: | ||
| - read it during preflight | ||
| - match task target paths/files to `path` scopes by longest repo-relative path prefix | ||
| - use domain scopes only when task wording, scope tags, or contract links make them relevant | ||
| - read nearest matching scope `README.md` only if present | ||
| - read only task-relevant scoped docs, then top-level docs as fallback for missing categories or repo-wide rules | ||
| - before trusting a path scope, verify the scoped source path still exists; if not, treat scoped docs as historical/stale and fall back to top-level/source evidence | ||
| - if multiple scopes match with equal confidence, read all relevant scope summaries and note ambiguity in preflight | ||
| Cross-scope contract rule: | ||
| - when touched code imports, exposes, serializes, persists, or validates data across module/package/service boundaries, read local scoped `CONTRACTS.md` and linked owner `CONTRACTS.md` if present | ||
| - owner contract docs are source of truth; consumer docs describe local usage/risk only | ||
| - if contract ownership is unclear, identify it as a risk before implementation |
+2
-1
| { | ||
| "name": "pi-agent-codebase-workflows", | ||
| "version": "0.1.1", | ||
| "version": "0.2.0", | ||
| "description": "Pi skills and prompt templates for codebase reconstruction, architecture-aware review, and safe changes.", | ||
@@ -28,2 +28,3 @@ "license": "MIT", | ||
| "prompts/", | ||
| "docs/", | ||
| "README.md", | ||
@@ -30,0 +31,0 @@ "LICENSE" |
@@ -10,2 +10,4 @@ --- | ||
| Use `docs/agent/SCOPES.md` if present to discover matching scoped docs before falling back to top-level docs. | ||
| Do not edit code. Produce the preflight output and say whether implementation should proceed now or wait for approval. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Write/update `docs/agent/REPO_INVENTORY.md`. Do not edit source code. | ||
| Write/update `docs/agent/REPO_INVENTORY.md`, or scoped `REPO_INVENTORY.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Read `docs/agent/REPO_INVENTORY.md`. Write/update `docs/agent/ARCHITECTURE.md`. Do not edit source code. | ||
| Read `docs/agent/REPO_INVENTORY.md` or matching scoped `REPO_INVENTORY.md`. Write/update `docs/agent/ARCHITECTURE.md`, or scoped `ARCHITECTURE.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Read `docs/agent/REPO_INVENTORY.md` and `docs/agent/ARCHITECTURE.md`. Write/update `docs/agent/DATA_MODEL.md` and `docs/agent/INVARIANTS.md`. Do not edit source code. | ||
| Read `docs/agent/REPO_INVENTORY.md` and `docs/agent/ARCHITECTURE.md`, or matching scoped prior docs. Write/update `docs/agent/DATA_MODEL.md` and `docs/agent/INVARIANTS.md`, or scoped `DATA_MODEL.md` and `INVARIANTS.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Read prior reconstruction docs. Write/update `docs/agent/DEPENDENCY_RULES.md` and `docs/agent/DESIGN_ISSUES.md`. Do not edit source code. | ||
| Read prior reconstruction docs, including matching scoped prior docs when focus is provided. Write/update `docs/agent/DEPENDENCY_RULES.md` and `docs/agent/DESIGN_ISSUES.md`, or scoped `DEPENDENCY_RULES.md` and `DESIGN_ISSUES.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Read architecture/data/invariants/dependency docs. Write/update `docs/agent/RISK_REGISTER.md`. Do not edit source code. | ||
| Read architecture/data/invariants/dependency docs, including matching scoped docs when focus is provided. Write/update `docs/agent/RISK_REGISTER.md`, or scoped `RISK_REGISTER.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If `docs/agent/SCOPES.md` exists, include compact scoped-doc discovery guidance in root `AGENTS.md`. | ||
| Write/update project-root `AGENTS.md` only. Merge with existing root `AGENTS.md` if present. Never create `docs/AGENTS.md` or `docs/agent/AGENTS.md`. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| Read architecture/data/invariants/dependency docs. Write/update `docs/agent/CHANGE_GUIDE.md`. Do not edit source code. | ||
| Read architecture/data/invariants/dependency docs, including matching scoped docs when focus is provided. Write/update `docs/agent/CHANGE_GUIDE.md`, or scoped `CHANGE_GUIDE.md` when focus is provided. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If `docs/agent/SCOPES.md` exists, use it to select relevant scoped docs and update scope status/currentness as needed. | ||
| Consolidate root `AGENTS.md` plus reconstruction docs. Reconcile contradictions without silently deleting disagreement evidence: resolve from source where possible, assign/clarify ownership for shared contracts where evidence supports it, or record unresolved disagreement as drift risk / `Known Unknown` with citations. De-duplicate repeated facts after preserving strongest evidence and materially different scope-specific observations. Do not edit source code. | ||
| Consolidate root `AGENTS.md` plus reconstruction docs. Reconcile contradictions without silently deleting disagreement evidence: resolve from source where possible, assign/clarify ownership for shared contracts where evidence supports it, or record unresolved disagreement as drift risk / `Known Unknown` with citations. Keep detailed scope-specific facts in scoped artifacts and summarize only stable repo-level guidance in top-level docs. De-duplicate repeated facts after preserving strongest evidence and materially different scope-specific observations. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, read matching scoped docs and make ADR scope explicit. | ||
| Write `docs/agent/adr/0001-observed-architecture.md`. Do not edit source code. |
@@ -9,4 +9,4 @@ --- | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope this pass to a module/package/app/service/path in large repos or monorepos. If focus is provided, read matching scoped risk/invariant/data/change-guide docs first. | ||
| Select top 3–5 risks to convert into tests. Produce plan only unless explicitly asked to implement tests. |
@@ -9,6 +9,6 @@ --- | ||
| Use focus to scope all passes to a module/package/app/service/path in large repos or monorepos. Produce scoped observations that can later be consolidated with other scoped artifacts. | ||
| Use focus to scope all passes to a module/package/app/service/path in large repos or monorepos. If focus is provided, write scoped artifacts under `docs/agent/scopes/by-path/<focus>/` for path focus or `docs/agent/scopes/by-domain/<slug>/` for domain focus, and update `docs/agent/SCOPES.md`. | ||
| First assess whether the repository is small/simple enough for reliable sequential reconstruction. If yes, run passes 1–10, writing artifacts under `docs/agent/` and keeping `AGENTS.md` at project root. | ||
| First assess whether the repository is small/simple enough for reliable sequential reconstruction. If yes, run passes 1–10, writing top-level artifacts under `docs/agent/` when unscoped or scoped artifacts under `docs/agent/scopes/**` when focused, and keeping `AGENTS.md` at project root. | ||
| If the repo proves too large or complex, complete the current pass and tell the user which numbered pass to run next. |
@@ -10,4 +10,4 @@ --- | ||
| Use scope to focus review on a module/package/app/service/path when diff spans multiple areas. | ||
| Use scope to focus review on a module/package/app/service/path when diff spans multiple areas. Use `docs/agent/SCOPES.md` if present to discover matching scoped docs and cross-scope contracts. | ||
| Review current diff. Do not edit code. Provide verdict, findings with severity/evidence/fix direction, missing tests, docs updates, drift risk, final recommendation. |
+28
-2
@@ -13,2 +13,7 @@ # pi-agent-codebase-workflows | ||
| ## Usage docs | ||
| - [Tutorial](docs/TUTORIAL.md) — end-to-end workflows for small repos, monorepos, scoped reconstruction, safe changes, reviews, consolidation, and legacy docs. | ||
| - [Troubleshooting](docs/TROUBLESHOOTING.md) — common reconstruction, scoping, contract, review, and validation issues. | ||
| ## Included prompt templates | ||
@@ -76,4 +81,22 @@ | ||
| Scoped passes should produce clearly labeled observations in `docs/agent/*.md`. Later `/recon-08-consolidate` can reconcile multiple scoped artifacts into repo-level guidance. | ||
| Without focus, reconstruction writes the traditional top-level `docs/agent/*.md` artifacts. With focus, reconstruction writes hierarchical scoped artifacts and updates `docs/agent/SCOPES.md`: | ||
| ```text | ||
| docs/agent/ | ||
| SCOPES.md | ||
| scopes/ | ||
| by-path/packages/api/ | ||
| README.md # optional local index for large/complex scopes | ||
| ARCHITECTURE.md | ||
| CONTRACTS.md | ||
| by-domain/auth-flow/ | ||
| README.md # optional local index for large/complex scopes | ||
| ARCHITECTURE.md | ||
| CONTRACTS.md | ||
| ``` | ||
| Top-level docs remain valid as repo-level summaries/fallbacks. This is backward-compatible with repositories reconstructed before scoped artifacts existed. Later `/recon-08-consolidate` can reconcile multiple scoped artifacts into repo-level guidance. | ||
| Safe-change and review workflows read `SCOPES.md` when present, match path scopes by longest prefix, and follow scoped `CONTRACTS.md` links for cross-module APIs, shared types, schemas, events, generated clients, and persistence boundaries. | ||
| Review and risk-fix prompts also accept scope/focus arguments for targeted reviews or fixes. | ||
@@ -87,2 +110,3 @@ | ||
| docs/agent/ | ||
| docs/agent/scopes/** | ||
| ``` | ||
@@ -104,3 +128,5 @@ | ||
| arch-code-review/SKILL.md | ||
| safe-change/SKILL.md | ||
| safe-change/ | ||
| SKILL.md | ||
| references/*.md | ||
| prompts/ | ||
@@ -107,0 +133,0 @@ *.md |
@@ -14,2 +14,18 @@ --- | ||
| ## Scoped Docs Discovery | ||
| Architecture review works with both legacy unscoped docs and hierarchical scoped docs. | ||
| If `docs/agent/SCOPES.md` is absent: | ||
| - review against top-level `docs/agent/*.md` only | ||
| If `docs/agent/SCOPES.md` is present: | ||
| - read it before selecting deeper docs | ||
| - match diff paths and explicit scope arguments to `path` scopes by longest repo-relative path prefix | ||
| - use domain scopes only when review target, scope tags, or contract links make them relevant | ||
| - read matching scoped `README.md` only if present, then task-relevant scoped docs | ||
| - read top-level docs as fallback for missing categories and repo-wide rules | ||
| - for cross-scope diffs, read relevant scoped `CONTRACTS.md` and `DEPENDENCY_RULES.md` from each touched owner/consumer scope | ||
| - verify matched source paths still exist before treating scoped docs as current | ||
| ## Rules | ||
@@ -21,2 +37,4 @@ | ||
| - Read only relevant deeper docs: | ||
| - `docs/agent/SCOPES.md` when present | ||
| - matched scoped `README.md` if present, and relevant scoped docs when present | ||
| - `docs/agent/ARCHITECTURE.md` | ||
@@ -28,2 +46,3 @@ - `docs/agent/DATA_MODEL.md` | ||
| - `docs/agent/CHANGE_GUIDE.md` | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
| - Prioritize correctness, architecture drift, data consistency, side-effect boundaries, public contracts, and tests. | ||
@@ -30,0 +49,0 @@ - Ignore style unless it affects maintainability or correctness. |
@@ -26,2 +26,4 @@ --- | ||
| Unscoped/repo-level artifacts: | ||
| ```text | ||
@@ -44,4 +46,35 @@ AGENTS.md | ||
| ## Focus Argument | ||
| Scoped artifacts, created only when a pass receives a focus argument: | ||
| ```text | ||
| docs/ | ||
| agent/ | ||
| scopes/ | ||
| by-path/<repo-relative-path>/ | ||
| README.md # optional local index for large/complex scopes | ||
| REPO_INVENTORY.md | ||
| ARCHITECTURE.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| CONTRACTS.md | ||
| by-domain/<domain-slug>/ | ||
| README.md # optional local index for large/complex scopes | ||
| ARCHITECTURE.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| CONTRACTS.md | ||
| ``` | ||
| `docs/agent/SCOPES.md` is created when scoped artifacts exist and acts as their registry. Top-level docs remain valid and are used as repo-level summaries/fallbacks. | ||
| ## Focus Argument and Scoped Artifacts | ||
| Pass prompts accept an optional `[focus]` argument. Use it to scope reconstruction to a module, package, app, service, directory, or bounded domain area, especially in monorepos. | ||
@@ -54,5 +87,14 @@ | ||
| When focus is absent: | ||
| - run the pass in unscoped mode | ||
| - write/update the standard top-level `docs/agent/*.md` artifact for the pass | ||
| - if scoped artifacts already exist, use them only when the pass explicitly calls for consolidation | ||
| When focus is provided: | ||
| - inspect only the focused area plus immediate dependencies, entry points, tests, and external boundaries needed to understand it | ||
| - write findings into the standard `docs/agent/*.md` artifacts with clear scope labels | ||
| - if focus is an existing repo-relative path, write to `docs/agent/scopes/by-path/<focus>/` | ||
| - if focus is not a path, write to `docs/agent/scopes/by-domain/<slug>/` | ||
| - update `docs/agent/SCOPES.md` with scope path, docs path, status, ownership, and external contracts | ||
| - optionally create/update scoped `README.md` only when helpful for large/complex scopes; otherwise rely on `SCOPES.md` as the index | ||
| - write pass findings into the scoped artifact for that pass, not into the top-level artifact | ||
| - include evidence paths that show the scoped boundary | ||
@@ -62,4 +104,29 @@ - mark interactions with the rest of the repo as external dependencies/boundaries | ||
| Scoped docs are additive and backward compatible. If a repository was reconstructed before scoped artifacts existed, keep existing top-level docs. Create `SCOPES.md` and scoped artifacts only when the first scoped pass runs. Later consolidation may summarize scoped findings into top-level docs. | ||
| This enables module/package-level reconstruction first, then later consolidation into repo-level artifacts. | ||
| ## Scope Registry and Contracts | ||
| `docs/agent/SCOPES.md` should stay compact and act as the discovery index for future workflows. | ||
| Suggested columns: | ||
| - Scope | ||
| - Kind: `path` / `domain` | ||
| - Docs path | ||
| - Status: `partial` / `current` / `stale` / `deprecated` | ||
| - Owns | ||
| - External contracts | ||
| - Last observed evidence | ||
| Each scoped directory may include `CONTRACTS.md` for cross-module APIs, shared types, schemas, events, generated clients, persistence boundaries, or public internal contracts. | ||
| Contract rules: | ||
| - every cross-scope contract should have one owner scope | ||
| - owner scope documents source of truth, compatibility rules, tests, and consumers | ||
| - consumer scopes link to owner contract and document local usage/risk only | ||
| - do not duplicate full contract rules across scopes | ||
| - generated clients reference source schema owner | ||
| - if ownership is unclear, record it as a known unknown or drift risk | ||
| ## Execution Modes | ||
@@ -112,3 +179,3 @@ | ||
| Task: write/update `docs/agent/REPO_INVENTORY.md`. | ||
| Task: write/update `docs/agent/REPO_INVENTORY.md`, or scoped `REPO_INVENTORY.md` when focus is provided. | ||
@@ -133,3 +200,3 @@ Rules: | ||
| Task: write/update `docs/agent/ARCHITECTURE.md`. | ||
| Task: write/update `docs/agent/ARCHITECTURE.md`, or scoped `ARCHITECTURE.md` when focus is provided. | ||
@@ -157,3 +224,3 @@ Find: | ||
| Task: write/update `docs/agent/DATA_MODEL.md` and `docs/agent/INVARIANTS.md`. | ||
| Task: write/update `docs/agent/DATA_MODEL.md` and `docs/agent/INVARIANTS.md`, or scoped `DATA_MODEL.md` and `INVARIANTS.md` when focus is provided. | ||
@@ -175,3 +242,3 @@ Focus only on semantically important data crossing module boundaries, persisted/serialized formats, configs, APIs, IDs, states, lifecycles. | ||
| Task: write/update `docs/agent/DEPENDENCY_RULES.md` and `docs/agent/DESIGN_ISSUES.md`. | ||
| Task: write/update `docs/agent/DEPENDENCY_RULES.md` and `docs/agent/DESIGN_ISSUES.md`, or scoped `DEPENDENCY_RULES.md` and `DESIGN_ISSUES.md` when focus is provided. | ||
@@ -200,3 +267,3 @@ Find: | ||
| Task: write/update `docs/agent/RISK_REGISTER.md`. | ||
| Task: write/update `docs/agent/RISK_REGISTER.md`, or scoped `RISK_REGISTER.md` when focus is provided. | ||
@@ -236,2 +303,3 @@ Find high-signal risks only: | ||
| - Include design/implementation/verification workflow. | ||
| - If `docs/agent/SCOPES.md` exists, include scoped-doc discovery guidance: future agents should check `SCOPES.md`, use longest matching path scope first, then repo-level fallback. | ||
| - Merge with existing root `AGENTS.md` if present. | ||
@@ -256,3 +324,3 @@ - Do not create `docs/AGENTS.md` or `docs/agent/AGENTS.md`. | ||
| Task: write/update `docs/agent/CHANGE_GUIDE.md`. | ||
| Task: write/update `docs/agent/CHANGE_GUIDE.md`, or scoped `CHANGE_GUIDE.md` when focus is provided. | ||
@@ -262,2 +330,3 @@ Required sections: | ||
| - How to locate affected slice/module | ||
| - How to discover matching scoped docs through `docs/agent/SCOPES.md` when present | ||
| - How to trace data flow | ||
@@ -273,3 +342,3 @@ - How to add/modify data structures | ||
| Read root `AGENTS.md` if it exists and all relevant `docs/agent/*.md` created by previous passes. | ||
| Read root `AGENTS.md` if it exists, all relevant top-level `docs/agent/*.md`, `docs/agent/SCOPES.md` if present, and relevant scoped docs under `docs/agent/scopes/**` created by previous passes. | ||
@@ -281,3 +350,6 @@ Task: consolidate artifacts. | ||
| - Reconcile contradictions; do not silently delete disagreement evidence. | ||
| - Read `docs/agent/SCOPES.md` first when present; use it to select relevant scoped summaries and changed/relevant scoped docs. | ||
| - When scoped passes disagree, resolve from source evidence where possible, assign/clarify ownership for shared contracts where evidence supports it, or record the disagreement as a drift risk / `Known Unknown` with cited evidence. | ||
| - Keep detailed scope-specific facts in scoped artifacts; summarize only stable repo-level guidance in top-level docs. | ||
| - Update `SCOPES.md` status/currentness when consolidation identifies stale, deprecated, or reconciled scopes. | ||
| - De-duplicate repeated facts only after preserving the strongest evidence paths and any materially different scope-specific observations. | ||
@@ -284,0 +356,0 @@ - Keep root `AGENTS.md` short and operational. |
+34
-172
@@ -16,3 +16,3 @@ --- | ||
| - Preflight comes first for every non-trivial task. | ||
| - Preflight comes first for every non-trivial task. Read `references/preflight.md`. | ||
| - Do not edit code during preflight/design/diagnosis unless explicitly asked. | ||
@@ -24,20 +24,37 @@ - Separate bug fixing, feature work, and refactoring. Never combine in one pass. | ||
| - Run focused validation first, then relevant broader validation. | ||
| - Update docs only when durable semantics changed: architecture, data model, invariants, dependency rules, public contracts, change workflow, or known risks. | ||
| - Update docs only when durable semantics changed. Read `references/docs-update.md` when docs may need updates. | ||
| - Do not explicitly read `AGENTS.md`; The harness injects root `AGENTS.md` automatically. | ||
| ## Universal Preflight | ||
| ## Scoped Docs | ||
| If `docs/agent/SCOPES.md` exists or task uses a module/package/app/service/path focus, read `references/scoped-docs.md` during preflight. Scoped docs are optional and backward-compatible; if absent, use top-level `docs/agent/*.md` only. | ||
| ## Workflow Selection | ||
| Classify task during preflight, then read the matching reference before design, diagnosis, or implementation: | ||
| - bug/error/regression/failing behavior -> `references/bug-fix.md` | ||
| - new behavior/API/UI capability/integration -> `references/feature.md` | ||
| - behavior-preserving structure change/design cleanup -> `references/refactoring.md` | ||
| - known risk, failing risk-derived test, or actionable `RISK_REGISTER.md` item -> `references/risk-fix.md` | ||
| - test-only task -> use `references/preflight.md`, preserve behavior, validate focused tests, update docs only if durable risk/invariant guidance changes | ||
| - docs-only task -> use `references/docs-update.md`, do not edit production code | ||
| ## Universal Preflight Summary | ||
| Read first: | ||
| - `docs/agent/CHANGE_GUIDE.md` if present | ||
| - `docs/agent/SCOPES.md` if present; then apply `references/scoped-docs.md` | ||
| Then read only docs relevant to task: | ||
| - `docs/agent/ARCHITECTURE.md` for module/flow changes | ||
| - `docs/agent/DATA_MODEL.md` for data changes | ||
| - `docs/agent/INVARIANTS.md` for rule-sensitive changes | ||
| - `docs/agent/DEPENDENCY_RULES.md` for imports/module boundaries | ||
| - `docs/agent/RISK_REGISTER.md` for risky areas | ||
| - `docs/agent/DESIGN_ISSUES.md` for refactoring/design work | ||
| Read only docs relevant to task: | ||
| - architecture docs for module/flow changes | ||
| - data model docs for data/schema/API/type changes | ||
| - invariant docs for rule-sensitive changes | ||
| - dependency rules for imports/module boundaries | ||
| - risk register for risky areas | ||
| - design issues for refactoring/design work | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
| Before editing code, produce: | ||
| 1. Task classification: bug fix / feature / refactoring / risk-fix / test-only / docs-only | ||
| 1. Task classification | ||
| 2. Relevant docs read | ||
@@ -50,164 +67,9 @@ 3. Affected slice/module/user flow | ||
| ## Bug Diagnosis | ||
| ## Approval Gates | ||
| After preflight, diagnose bug before editing. | ||
| - Bug fixes: diagnose and propose minimal fix before implementation. | ||
| - Features: design and propose test plan before implementation. | ||
| - Refactors: design staged behavior-preserving plan before implementation. | ||
| - Risk fixes: select one failing test/risk cluster and propose minimal fix before implementation. | ||
| Tasks: | ||
| 1. Reproduce or locate bug. | ||
| 2. Identify expected behavior. | ||
| 3. Identify violated invariant, contract, or public behavior. | ||
| 4. Identify affected files/modules. | ||
| 5. Explain likely root cause. | ||
| 6. Propose minimal fix plan. | ||
| 7. Propose regression test and validation commands. | ||
| Stop unless user approved implementation. | ||
| ## Bug Implementation | ||
| Continue from approved bug-fix plan. | ||
| Rules: | ||
| - Follow approved plan. | ||
| - Change production code only where necessary. | ||
| - Add/update regression test unless impossible; explain if impossible. | ||
| - Do not opportunistically refactor. | ||
| - Run focused test first, then relevant broader suite. | ||
| - Update `docs/agent/RISK_REGISTER.md` if bug corresponds to known/new risk. | ||
| - Update `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, or `docs/agent/CHANGE_GUIDE.md` only if fix clarifies/changes durable rules. | ||
| Output: | ||
| - Files changed | ||
| - Root cause fixed | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining risks/follow-up | ||
| ## Feature Design | ||
| After preflight, design before implementation. | ||
| Tasks: | ||
| 1. Feature summary | ||
| 2. Affected user/execution flow | ||
| 3. Affected modules/files | ||
| 4. Data model impact | ||
| 5. Invariants affected or introduced | ||
| 6. Side effects needed and boundaries | ||
| 7. Dependency rule impact | ||
| 8. Risks | ||
| 9. Test plan | ||
| 10. Minimal implementation plan | ||
| 11. Documentation update plan | ||
| 12. Blocking open questions only | ||
| Rules: | ||
| - Prefer extending existing concepts over new abstractions. | ||
| - Keep side effects at existing side-effect boundaries. | ||
| - Do not introduce global/shared utilities unless justified. | ||
| - Stop unless user approved implementation. | ||
| ## Feature Implementation | ||
| Continue from approved feature design. | ||
| Rules: | ||
| - Follow approved design. | ||
| - Keep changes inside affected slice/module when possible. | ||
| - No unrelated refactoring. | ||
| - Add/update tests according to test plan. | ||
| - Preserve existing invariants. | ||
| - Keep side effects behind existing boundaries. | ||
| - Update docs only for durable semantic changes. | ||
| - Run focused tests, then broader validation. | ||
| Output: | ||
| - Files changed | ||
| - Feature behavior implemented | ||
| - Data model changes | ||
| - Invariants added/changed | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining risks/limitations | ||
| ## Refactoring Design | ||
| After preflight, design refactor before edits. | ||
| Rules: | ||
| - No behavior change. | ||
| - Treat refactoring as separate use case. | ||
| - Identify smell/design issue precisely with evidence. | ||
| - Identify tests protecting behavior. | ||
| - If tests insufficient, propose characterization tests first. | ||
| - Prefer staged refactorings over rewrites. | ||
| - Do not introduce new architecture style unless explicitly requested. | ||
| Output: | ||
| - Refactoring goal | ||
| - Current design problem | ||
| - Evidence | ||
| - Behavior to preserve | ||
| - Affected files/modules | ||
| - Invariants to preserve | ||
| - Required characterization tests | ||
| - Refactoring stages | ||
| - Validation plan | ||
| - Rollback strategy | ||
| - Documentation update plan | ||
| Stop unless user approved implementation. | ||
| ## Refactoring Implementation | ||
| Continue from approved refactoring design, one smallest safe stage. | ||
| Rules: | ||
| - Preserve behavior. | ||
| - Do not combine with feature work. | ||
| - Do not fix unrelated bugs unless they block refactor. | ||
| - Add characterization tests before behavior-sensitive changes. | ||
| - Keep each change mechanically understandable. | ||
| - Run tests after each meaningful stage. | ||
| - Update docs only if durable structure/dependency/change guidance changed. | ||
| Output: | ||
| - Stage completed | ||
| - Files changed | ||
| - Behavior preserved | ||
| - Tests added/updated | ||
| - Validation results | ||
| - Documentation updates | ||
| - Remaining stages | ||
| ## Risk-Fix Pass | ||
| Use when risk-derived tests fail or `RISK_REGISTER.md` identifies actionable risks. | ||
| Read first: | ||
| - `docs/agent/CHANGE_GUIDE.md` | ||
| - `docs/agent/RISK_REGISTER.md` | ||
| - `docs/agent/INVARIANTS.md` | ||
| - `docs/agent/DATA_MODEL.md` | ||
| Rules: | ||
| - Do not fix all failing tests at once. | ||
| - Select one failing test or tightly related risk cluster. | ||
| - Prioritize: critical data corruption, security/safety, persistence/state inconsistency, public API/schema breakage, incorrect domain behavior, architecture boundary violation, performance/cleanup. | ||
| - Explain violated invariant. | ||
| - Identify minimal production-code change. | ||
| - Do not change test unless demonstrably wrong. | ||
| - Do not refactor unrelated code. | ||
| - Run focused test first, then surrounding suite. | ||
| - Update `docs/agent/RISK_REGISTER.md` status. | ||
| Output: | ||
| - Selected failing test/risk cluster | ||
| - Root cause | ||
| - Invariant violated | ||
| - Minimal fix plan | ||
| - Files changed | ||
| - Validation result | ||
| - Remaining failing tests/risks | ||
| Stop for approval unless user explicitly asked to implement immediately. |
No alert changes
Improved metrics
- Total package byte prevSize
56026
64.41%- Number of package files
35
34.62%- Number of lines in readme file
133
24.3%No dependency changes