From 2ad2ddf38ba12194f5fffa10904c1915de331bae Mon Sep 17 00:00:00 2001 From: mo Date: Sun, 5 Apr 2026 19:39:56 -0400 Subject: [PATCH] Add operational runbooks and decisions stub --- docs/00-governance/CLEANUP_LOG.md | 1 + docs/00-governance/decisions.md | 15 ++++++ docs/02-runbooks/backtest_review_workflow.md | 36 ++++++++++++++ .../compile_error_triage_workflow.md | 30 ++++++++++++ docs/02-runbooks/live_test_review_workflow.md | 36 ++++++++++++++ docs/02-runbooks/repo_cleanup_workflow.md | 25 ++++++++++ docs/02-runbooks/session_start_workflow.md | 26 ++++++++++ docs/02-runbooks/spec_to_build_workflow.md | 49 +++++++++++++++++++ 8 files changed, 218 insertions(+) create mode 100644 docs/02-runbooks/backtest_review_workflow.md create mode 100644 docs/02-runbooks/compile_error_triage_workflow.md create mode 100644 docs/02-runbooks/live_test_review_workflow.md create mode 100644 docs/02-runbooks/repo_cleanup_workflow.md create mode 100644 docs/02-runbooks/session_start_workflow.md create mode 100644 docs/02-runbooks/spec_to_build_workflow.md diff --git a/docs/00-governance/CLEANUP_LOG.md b/docs/00-governance/CLEANUP_LOG.md index 4b15a40..f73259e 100644 --- a/docs/00-governance/CLEANUP_LOG.md +++ b/docs/00-governance/CLEANUP_LOG.md @@ -20,3 +20,4 @@ - `docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md` - Added a softer revision note to `README.md` instead of a historical warning. - Marked `docs/INDEX.md` historical in place because it currently misdirects navigation. +- Added follow-up debt: shared metrics vocabulary currently duplicated in `docs/02-runbooks/backtest_review_workflow.md` and `docs/02-runbooks/live_test_review_workflow.md`; later extract to shared governance doc `docs/00-governance/metrics_vocabulary.md`. diff --git a/docs/00-governance/decisions.md b/docs/00-governance/decisions.md index e69de29..beae8e4 100644 --- a/docs/00-governance/decisions.md +++ b/docs/00-governance/decisions.md @@ -0,0 +1,15 @@ +# Architecture Decisions + +Use this file to record durable project decisions that affect implementation patterns, interfaces, or workflow. + +## Decision Template +- ID: DEC-YYYYMMDD-XX +- Date: +- Status: proposed | accepted | superseded +- Context: +- Decision: +- Consequences: +- Related Files: + +## Decision Log +- No decisions recorded yet. diff --git a/docs/02-runbooks/backtest_review_workflow.md b/docs/02-runbooks/backtest_review_workflow.md new file mode 100644 index 0000000..42c5ee2 --- /dev/null +++ b/docs/02-runbooks/backtest_review_workflow.md @@ -0,0 +1,36 @@ +# Backtest Review Workflow + +## Purpose +Provide a consistent pass/fail review process for strategy backtest output. + +## Inputs +- Backtest report (date range, instrument, timeframe, settings). +- Strategy version/commit reference. +- Risk and execution assumptions used for the run. + +## Review Steps +1. Confirm run metadata is complete and reproducible. +2. Validate data window and session settings match test intent. +3. Review shared metrics vocabulary: + - Net Profit + - Profit Factor + - Max Drawdown + - Win Rate + - Average Trade + - Expectancy + - Trade Count +4. Check risk behavior consistency (drawdown shape, loss clustering, streak behavior). +5. Compare against prior baseline and flag material regressions. +6. Record decision: `pass`, `pass_with_conditions`, or `fail`. + +## Required Output +- Backtest Review Note with: + - metadata, + - metrics snapshot, + - baseline delta, + - decision, + - required follow-ups. + +## Exit Criteria +- Review note is stored with clear decision and rationale. +- Any follow-up actions are captured as tasks. diff --git a/docs/02-runbooks/compile_error_triage_workflow.md b/docs/02-runbooks/compile_error_triage_workflow.md new file mode 100644 index 0000000..e59da07 --- /dev/null +++ b/docs/02-runbooks/compile_error_triage_workflow.md @@ -0,0 +1,30 @@ +# Compile Error Triage Workflow + +## Purpose +Resolve compile errors quickly using smallest-safe changes and durable prevention notes. + +## Inputs +- Failing command output (`./verify-build.bat` or `dotnet test`). +- File scope constraints for current task. + +## Steps +1. Reproduce with the same command to confirm current error set. +2. Classify each error: + - missing type/namespace, + - bad override/signature, + - wrong overload/argument, + - C# 5.0 compatibility violation. +3. Verify any NinjaScript/API signatures against NT8 docs before editing. +4. Apply minimum-diff fix in scoped files only. +5. Re-run `./verify-build.bat`. +6. Run focused tests for the impacted area. +7. If issue is non-trivial, add concise prevention notes to governance docs. + +## Required Output +- Error-to-fix mapping (error code, root cause, fix). +- Verification evidence (build/test commands and results). + +## Exit Criteria +- Build passes. +- Relevant tests pass. +- Non-trivial learnings are captured. diff --git a/docs/02-runbooks/live_test_review_workflow.md b/docs/02-runbooks/live_test_review_workflow.md new file mode 100644 index 0000000..9d91b66 --- /dev/null +++ b/docs/02-runbooks/live_test_review_workflow.md @@ -0,0 +1,36 @@ +# Live Test Review Workflow + +## Purpose +Review paper/live-forward test behavior using the same decision discipline as backtest review. + +## Inputs +- Live test window and environment details (paper/live, broker feed, session template). +- Strategy version/commit reference. +- Execution logs and order/rejection events. + +## Review Steps +1. Confirm environment and deployment metadata. +2. Validate runtime stability (disconnects, errors, unexpected restarts). +3. Review shared metrics vocabulary: + - Net Profit + - Profit Factor + - Max Drawdown + - Win Rate + - Average Trade + - Expectancy + - Trade Count +4. Inspect execution quality (slippage, missed fills, rejection frequency, latency anomalies). +5. Compare live metrics to backtest expectations and tolerance bands. +6. Record decision: `promote`, `extend_test`, or `hold`. + +## Required Output +- Live Test Review Note with: + - environment details, + - key metrics, + - execution anomalies, + - decision, + - next actions. + +## Exit Criteria +- Review note is complete and decision is explicit. +- Any blockers or promotion prerequisites are tracked as tasks. diff --git a/docs/02-runbooks/repo_cleanup_workflow.md b/docs/02-runbooks/repo_cleanup_workflow.md new file mode 100644 index 0000000..a9c1b5d --- /dev/null +++ b/docs/02-runbooks/repo_cleanup_workflow.md @@ -0,0 +1,25 @@ +# Repo Cleanup Workflow + +## Purpose +Keep repository documentation and task metadata clean without changing functional behavior. + +## Inputs +- Cleanup trigger (stale docs, duplicate guidance, archival need, naming drift). +- Current governance priorities from `docs/00-governance/active_work.md`. + +## Steps +1. Confirm cleanup scope and impacted files. +2. Ensure no production code changes are included. +3. Remove stale or duplicate sections that are no longer authoritative. +4. Consolidate references so canonical docs remain in `docs/00-governance/`. +5. Log cleanup action and any remaining debt in `docs/00-governance/CLEANUP_LOG.md`. +6. Verify links/paths and runbook references after edits. + +## Required Output +- List of files cleaned and reason for each. +- Cleanup debt notes for deferred follow-ups. + +## Exit Criteria +- Cleanup scope is complete. +- `CLEANUP_LOG.md` is updated. +- No code files were modified. diff --git a/docs/02-runbooks/session_start_workflow.md b/docs/02-runbooks/session_start_workflow.md new file mode 100644 index 0000000..261caa3 --- /dev/null +++ b/docs/02-runbooks/session_start_workflow.md @@ -0,0 +1,26 @@ +# Session Start Workflow + +## Purpose +Start each implementation session with correct scope, context, and task state before editing files. + +## Inputs +- Current priority task from Archon. +- Governance docs in `docs/00-governance/`. + +## Steps +1. Open and read in order: + - `docs/00-governance/executive_summary.md` + - `docs/00-governance/current_status.md` + - `docs/00-governance/active_work.md` + - `docs/00-governance/architecture.md` + - `docs/00-governance/roadmap.md` +2. Pull current task details from Archon and confirm acceptance criteria. +3. Confirm allowed file scope from task spec and `.kilocode/rules/file_boundaries.md`. +4. Move task status in Archon from `todo` to `doing`. +5. Capture a short execution plan (3-6 bullets) tied to acceptance criteria. +6. Begin implementation with minimum-diff edits only in scoped files. + +## Exit Criteria +- Task is set to `doing`. +- Scope boundaries are explicitly confirmed. +- Work plan exists and maps to task acceptance criteria. diff --git a/docs/02-runbooks/spec_to_build_workflow.md b/docs/02-runbooks/spec_to_build_workflow.md new file mode 100644 index 0000000..2b91a91 --- /dev/null +++ b/docs/02-runbooks/spec_to_build_workflow.md @@ -0,0 +1,49 @@ +# Spec-to-Build Workflow + +## Purpose +Convert an approved spec into implementation-ready work with explicit tool handoffs and verifiable artifacts. + +## Roles +- Planner: decomposes spec into implementable tasks. +- Implementer: edits code within scope. +- Verifier: runs required build and tests. + +## Tool Handoffs and Artifact Passing +1. **Spec Intake (Planner)** + - Tool: Archon task/project view. + - Input artifact: approved spec text. + - Output artifact: `Task Brief` containing objective, scope, constraints, acceptance criteria. +2. **Task Breakdown (Planner)** + - Tool: Archon task board. + - Input artifact: `Task Brief`. + - Output artifact: ordered subtasks with file scope and done criteria. +3. **Implementation (Implementer)** + - Tool: repository editor + scoped files. + - Input artifact: ordered subtasks. + - Output artifact: minimal code/doc diffs limited to allowed files. +4. **Build Verification (Verifier)** + - Tool: `./verify-build.bat`. + - Input artifact: working tree changes. + - Output artifact: pass/fail result with error details if failed. +5. **Focused Tests (Verifier)** + - Tool: `dotnet test` with area filter. + - Input artifact: verified build output. + - Output artifact: test evidence (command + pass/fail + failing test IDs). +6. **Task State Update (Planner/Implementer)** + - Tool: Archon task board. + - Input artifact: verification evidence. + - Output artifact: task moved `doing` -> `review` with implementation notes and evidence links. + +## Required Artifact Bundle for Review +- `Task Brief` (objective/scope/constraints/acceptance criteria). +- Subtask list with scoped files. +- Diff summary (files changed + why). +- Verification evidence: + - `./verify-build.bat` result. + - Relevant `dotnet test` result. +- Known limitations or follow-up items. + +## Exit Criteria +- Acceptance criteria are satisfied. +- Evidence bundle is complete. +- Task status is `review`.