| 1 | # SOW-YYYYMMDD-<slug> - <Title> |
| 2 | |
| 3 | ## Status |
| 4 | |
| 5 | Status: planning | ready | in-progress | paused | completed |
| 6 | |
| 7 | `planning` means analysis or decisions are incomplete. `ready` means the |
| 8 | Pre-Implementation Gate is complete and, where the goal-approval round ("Plan |
| 9 | before non-trivial work") applies, the user has approved the goal and plan. `completed` is a |
| 10 | transient branch-local state before deleting this SOW working file before merge. SOW files live only under `.agents/sow/active/` on feature branches and |
| 11 | MUST NOT be merged to `master`. |
| 12 | |
| 13 | Sub-state: <short current truth> |
| 14 | |
| 15 | ## Requirements |
| 16 | |
| 17 | ### Purpose |
| 18 | |
| 19 | <User-stated purpose. All recommendations must align with this.> |
| 20 | |
| 21 | ### User Request |
| 22 | |
| 23 | <Concise quote or faithful summary. Do not lose constraints.> |
| 24 | |
| 25 | Regresses (optional): PR #NNNNN |
| 26 | |
| 27 | ### Assistant Understanding |
| 28 | |
| 29 | Facts: |
| 30 | |
| 31 | - <Established from user/project/code/specs.> |
| 32 | |
| 33 | Inferences: |
| 34 | |
| 35 | - <Reasoned but not directly stated.> |
| 36 | |
| 37 | Unknowns: |
| 38 | |
| 39 | - <Only real unknowns that cannot be resolved by investigation.> |
| 40 | |
| 41 | ### Acceptance Criteria |
| 42 | |
| 43 | - <Outcome with verification method.> |
| 44 | - <Outcome with verification method.> |
| 45 | |
| 46 | ## Analysis |
| 47 | |
| 48 | Sources checked: |
| 49 | |
| 50 | - <file/source> |
| 51 | |
| 52 | Current state: |
| 53 | |
| 54 | - <evidence> |
| 55 | |
| 56 | Risks: |
| 57 | |
| 58 | - <risk and implication> |
| 59 | |
| 60 | ## Pre-Implementation Gate |
| 61 | |
| 62 | Status: blocked | ready | needs-user-decision |
| 63 | |
| 64 | Problem / root-cause model: |
| 65 | |
| 66 | - <What is happening, why it is happening, and evidence supporting that model.> |
| 67 | |
| 68 | Evidence reviewed: |
| 69 | |
| 70 | - <Specs, code, docs, tests, logs, traces, prior PRs/issues, external references.> |
| 71 | - <For mirrored open-source repositories: cite `owner/repo @ commit` and repository-relative paths; never paste machine-specific absolute mirror paths (the mirror lives at `${NETDATA_REPOS_DIR}`).> |
| 72 | |
| 73 | Affected contracts and surfaces: |
| 74 | |
| 75 | - <APIs, schemas, files, commands, UI, docs, specs, skills, tests, integrations, operators, users.> |
| 76 | |
| 77 | Clean-end-state target: |
| 78 | |
| 79 | - <The structure the codebase should have once the approved scope is fully delivered.> |
| 80 | - Removed as redundant (i): <code/config/docs/tests this change makes redundant.> |
| 81 | - Excluded coupled items (ii): <coupled items NOT part of this clean end state, each with reason + scope source.> |
| 82 | - Reference search (when a path/contract is replaced): <command(s) run + result; every surviving reference mapped to (i)/(ii), or the target is incomplete.> |
| 83 | |
| 84 | Existing patterns to reuse: |
| 85 | |
| 86 | - <Local modules, helpers, conventions, tests, and docs that shape the implementation.> |
| 87 | |
| 88 | Risk and blast radius: |
| 89 | |
| 90 | - <Regression, compatibility, performance, security, data loss, migration, rollout, and operational risks.> |
| 91 | |
| 92 | Sensitive data handling plan: |
| 93 | |
| 94 | - <Whether the work may expose secrets, credentials, bearer tokens, SNMP communities, community/customer data, personal data, non-private customer-identifying IPs, private endpoints, or proprietary incident details; how evidence will be redacted in SOWs, specs, docs, skills, instructions, and code comments.> |
| 95 | |
| 96 | Implementation plan: |
| 97 | |
| 98 | 1. <Ordered chunk with scope, dependencies, and likely files/modules.> |
| 99 | 2. <Ordered chunk with scope, dependencies, and likely files/modules.> |
| 100 | |
| 101 | Validation plan: |
| 102 | |
| 103 | - <Tests, fixtures, manual checks, real-use evidence, review passes, same-failure searches.> |
| 104 | |
| 105 | Artifact impact plan: |
| 106 | |
| 107 | - AGENTS.md: <expected update or reason likely unaffected> |
| 108 | - Runtime project skills: <expected update or reason likely unaffected> |
| 109 | - Specs: <expected update or reason likely unaffected> |
| 110 | - End-user/operator docs: <expected update or reason likely unaffected> |
| 111 | - End-user/operator skills: <expected update or reason likely unaffected> |
| 112 | - SOW lifecycle: <branch-local working file; durable-knowledge targets (specs/skills/docs/code/tests); delete-before-merge; regression = new linked SOW; follow-up issues> |
| 113 | |
| 114 | Open-source reference evidence: |
| 115 | |
| 116 | - <If local mirrored repositories under `${NETDATA_REPOS_DIR}` were checked, list each as `owner/repo @ commit` plus repository-relative paths. If none were checked, record why external OSS references were not relevant.> |
| 117 | |
| 118 | Open decisions: |
| 119 | |
| 120 | - <Resolved decision, or numbered options that block implementation until the user decides.> |
| 121 | |
| 122 | ## Implications And Decisions |
| 123 | |
| 124 | <Numbered user decisions, options, selection, and reasoning. User decisions must be recorded before implementation.> |
| 125 | |
| 126 | ## Plan |
| 127 | |
| 128 | 1. <chunk, scope, risk, dependencies> |
| 129 | 2. <chunk, scope, risk, dependencies> |
| 130 | |
| 131 | ## Execution Log |
| 132 | |
| 133 | ### YYYY-MM-DD |
| 134 | |
| 135 | - <files touched, decisions, deviations, reviewers> |
| 136 | |
| 137 | ## Validation |
| 138 | |
| 139 | Acceptance criteria evidence: |
| 140 | |
| 141 | - <evidence> |
| 142 | |
| 143 | Tests or equivalent validation: |
| 144 | |
| 145 | - <command/output summary> |
| 146 | |
| 147 | Real-use evidence: |
| 148 | |
| 149 | - <manual/API/CLI/UI path> |
| 150 | |
| 151 | Reviewer findings: |
| 152 | |
| 153 | - <reviewer and findings> |
| 154 | |
| 155 | Same-failure scan: |
| 156 | |
| 157 | - <search and result> |
| 158 | |
| 159 | Sensitive data gate: |
| 160 | |
| 161 | - <Confirm durable artifacts contain no raw secrets, credentials, bearer tokens, SNMP communities, community member names, customer names, personal data, non-private customer-identifying IPs, private endpoints, or proprietary incident details; note redactions used.> |
| 162 | |
| 163 | ## Artifact Maintenance Gate |
| 164 | |
| 165 | - AGENTS.md: <updated path or evidence-backed reason no update was needed> |
| 166 | - Runtime project skills: <updated .agents/skills/project-*/ path or evidence-backed reason no update was needed> |
| 167 | - Specs: <updated .agents/sow/specs/ path or evidence-backed reason no update was needed> |
| 168 | - End-user/operator docs: <updated docs/runbooks/help paths or evidence-backed reason none were affected> |
| 169 | - End-user/operator skills: <updated output/reference skill paths or evidence-backed reason none were affected> |
| 170 | - SOW lifecycle: <durable knowledge transferred to specs/skills/docs/code/tests; follow-ups moved to GitHub issues or rejected; `Status: completed` set; SOW working file deleted from the branch before merge so no SOW file reaches `master`; regression-as-new-SOW handling recorded> |
| 171 | |
| 172 | Specs update: |
| 173 | |
| 174 | - <updated spec or specific reason no update was needed> |
| 175 | |
| 176 | Project skills update: |
| 177 | |
| 178 | - <updated runtime project skill or specific reason no update was needed> |
| 179 | |
| 180 | End-user/operator docs update: |
| 181 | |
| 182 | - <updated docs or evidence-backed reason none were affected> |
| 183 | |
| 184 | End-user/operator skills update: |
| 185 | |
| 186 | - <updated output/reference skills affected by docs/spec changes, or evidence-backed reason none were affected> |
| 187 | |
| 188 | Lessons: |
| 189 | |
| 190 | - <lesson or specific reason none> |
| 191 | |
| 192 | Follow-up mapping: |
| 193 | |
| 194 | - <implemented/rejected/GitHub issue link> |
| 195 | |
| 196 | ## Outcome |
| 197 | |
| 198 | Pending. |
| 199 | |
| 200 | ## Lessons Extracted |
| 201 | |
| 202 | Pending. |
| 203 | |
| 204 | ## Follow-up Issues |
| 205 | |
| 206 | None yet. |