SOW-YYYYMMDD-<slug> - <Title>

Status

Status: planning | ready | in-progress | paused | completed

planning means analysis or decisions are incomplete. ready means the Pre-Implementation Gate is complete and, where the goal-approval round ("Plan before non-trivial work") applies, the user has approved the goal and plan. completed means work is validated and durable memory transferred. SOW files are local-only working memory under .agents/sow/q/ (gitignored) and are never committed.

Sub-state: <short current truth>

Requirements

Purpose

<User-stated purpose. All recommendations must align with this.>

User Request

Regresses (optional): PR #NNNNN

Assistant Understanding

Facts:

<Established from user/project/code/specs.>

Inferences:

<Reasoned but not directly stated.>

Unknowns:

<Only real unknowns that cannot be resolved by investigation.>

Acceptance Criteria

<Outcome with verification method.>
<Outcome with verification method.>

Analysis

Sources checked:

<file/source>

Current state:

<evidence>

Risks:

<risk and implication>

Pre-Implementation Gate

Status: blocked | ready | needs-user-decision

Problem / root-cause model:

<What is happening, why it is happening, and evidence supporting that model.>

Evidence reviewed:

<Specs, code, docs, tests, logs, traces, prior PRs/issues, external references.>
<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}).>

Affected contracts and surfaces:

<APIs, schemas, files, commands, UI, docs, specs, skills, tests, integrations, operators, users.>

Clean-end-state target:

<The structure the codebase should have once the approved scope is fully delivered.>
Removed as redundant (i): <code/config/docs/tests this change makes redundant.>
Excluded coupled items (ii): <coupled items NOT part of this clean end state, each with reason + scope source.>
Reference search (when a path/contract is replaced): <command(s) run + result; every surviving reference mapped to (i)/(ii), or the target is incomplete.>

Existing patterns to reuse:

<Local modules, helpers, conventions, tests, and docs that shape the implementation.>

Risk and blast radius:

<Regression, compatibility, performance, security, data loss, migration, rollout, and operational risks.>

Sensitive data handling plan:

<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.>

Implementation plan:

<Ordered chunk with scope, dependencies, and likely files/modules.>
<Ordered chunk with scope, dependencies, and likely files/modules.>

Validation plan:

<Tests, fixtures, manual checks, real-use evidence, review passes, same-failure searches.>

Artifact impact plan:

AGENTS.md: <expected update or reason likely unaffected>
Runtime project skills: <expected update or reason likely unaffected>
Specs: <expected update or reason likely unaffected>
End-user/operator docs: <expected update or reason likely unaffected>
End-user/operator skills: <expected update or reason likely unaffected>
SOW lifecycle: <local-only working file under .agents/sow/q/ (never committed); durable-knowledge targets (skills/docs/code/tests); regression = new linked SOW; follow-up issues>

Open-source reference evidence:

<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.>

Open decisions:

<Resolved decision, or numbered options that block implementation until the user decides.>

Implications And Decisions

Plan

<chunk, scope, risk, dependencies>
<chunk, scope, risk, dependencies>

Execution Log

YYYY-MM-DD

<Material state transitions, files touched, decisions, deviations, validation, and reviewers. Keep this a current-state handoff: consolidate superseded rounds and do not reproduce the conversation or every review nit.>

Workflow Friction & Rule Gaps

Running capture of anything that suggests a rule or workflow change: a rule that was missing, ambiguous, or slowed the work; a practice worth codifying; a review pattern that helped. Jot entries as they happen — do not reconstruct them from memory at close. Every entry is triaged before completion (see the Artifact Maintenance Gate).

<observation + which artifact it may touch (AGENTS.md / project skill / spec / SOW template)>

Validation

Acceptance criteria evidence:

<evidence>

Tests or equivalent validation:

<command/output summary>

Real-use evidence:

<manual/API/CLI/UI path>

Reviewer findings:

<reviewer and findings>

Same-failure scan:

<search and result>

Sensitive data gate:

<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.>

Artifact Maintenance Gate

AGENTS.md: <updated path or evidence-backed reason no update was needed>
Runtime project skills: <updated .agents/skills/project-*/ path or evidence-backed reason no update was needed>
Specs: <updated .agents/sow/specs/ path or evidence-backed reason no update was needed>
End-user/operator docs: <updated docs/runbooks/help paths or evidence-backed reason none were affected>
End-user/operator skills: <updated output/reference skill paths or evidence-backed reason none were affected>
SOW lifecycle: <durable knowledge transferred to skills/docs/code/tests; follow-ups moved to GitHub issues or rejected; Status: completed set; SOW working file is local-only under .agents/sow/q/ and never committed; regression-as-new-SOW handling recorded>
Workflow friction triaged: <each Workflow Friction & Rule Gaps entry resolved to a rule update (file + change), an evidence-backed rejection, or a tracked follow-up; "no workflow friction arose" if the section is empty>

Specs update:

<updated spec or specific reason no update was needed>

Project skills update:

<updated runtime project skill or specific reason no update was needed>

End-user/operator docs update:

<updated docs or evidence-backed reason none were affected>

End-user/operator skills update:

<updated output/reference skills affected by docs/spec changes, or evidence-backed reason none were affected>

Lessons:

<lesson or specific reason none>

Follow-up mapping:

<implemented/rejected/GitHub issue link>

Outcome

Pending.

Lessons Extracted