@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/execute-work/SKILL.md

@@ -1,122 +1,146 @@
 ---
 name: execute-work
-description: "Use when preparing and carrying out requested or approved concrete work, including implementation, fixes, prototypes, documentation, configuration, and repository maintenance."
+description: "Use for any task that uses tools: reading or searching a repository, running commands, diagnosing, and any work that changes code, files or settings: implementing a feature, fixing a bug, adding or changing behavior, configuring, prototyping, refactoring, simplifying or cleaning up code, deleting dead code, or maintaining a project. Also use when designing or changing modules, interfaces, data models, state, error handling or dependencies; when something fails, breaks, regresses or slows down and the cause is unknown, or a fix did not hold; when migrating users, data, a schema, a service or traffic to a replacement and removing the old path; and when adding edge-case handling or code comments. Read it before your first tool call on a task, even a small or read-only one: it reads the request for its asks and implied requirements, finds what the change touches before you edit, and reviews and reports the result."
 ---
 
 # Execute Work
 
-Produce the agreed concrete result through supported preparation, bounded execution, verification, and correction. Do not make the user supply an implementation plan when the request authorizes you to figure it out.
+Carry out a task from its first tool call to a checked result: the reading, searching and diagnosis before a change, and the change itself. The work agreement says what to build; work out how yourself when the request leaves that to you.
 
-Workflow establishes the work agreement and coordinates authority, ownership, and the user-facing return boundary. Execute Work owns implementation preparation and continuation within it. Task memory belongs to Track Work; governing choices remain with the user.
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
 
-## Establish The Execution Basis
-
-Consume the current request, accepted discussion, governing artifacts, and relevant live state. Establish which assignment and stopping condition currently apply; do not combine older directions with a superseding contract. Resolve material ambiguity before dependent effects. Do not restart discovery because execution was selected.
-
-Before production changes, establish:
-
-- **Outcome:** the required result, constraints, non-goals, and acceptance boundary.
-- **Approach:** the supported mechanism, affected code or artifacts, dependencies, and necessary ordering.
-- **Evidence:** a check or observation capable of disagreeing with the result.
-- **Agreement:** covered effects, extent of work, and when to return to the user.
-
-Before effects, check whether a selected checkpoint or separately controlled boundary is already due. Do not cross it while unresolved.
+## Routes
 
-If the agreement is materially unclear, return to [Workflow](../workflow/SKILL.md) before the unsettled execution. A clear request may already establish it; do not ask again merely to perform a ritual.
+Read a reference only when its situation arises.
 
-An agreement to fix a bug can cover investigation before the remedy is known. An agreement to return a plan does not cover production edits. Distinguish evidence gathering from implementation even when both are authorized.
+| Situation | Read |
+| --- | --- |
+| Before the first production change: finding the callers, readers, writers, tests and docs a change touches | Run [touch-map](scripts/touch-map.mjs), as Establish The Execution Basis says |
+| Before reporting a change as done | Run [self-review](scripts/self-review.mjs), as Check, Then Continue Or Return says |
+| A change, even one line, to permissions, public behavior, canonical state or failure semantics, or one that spreads a policy across callers | [design: Start With The Required Outcome](references/design.md#start-with-the-required-outcome) |
+| Building on a representation, identity, ownership or algorithm choice that dependent work would redo if wrong | [design: Settle The Choices](references/design.md#settle-the-choices) |
+| A new or changed interface between parts, or choosing which part owns a decision | [design: Interfaces](references/design.md#interfaces) |
+| State that must survive a failure: partial effects, retries, concurrent writers, recovery | [design: State And Failure](references/design.md#state-and-failure) |
+| Module cycles, layering, dependency direction, or extracting shared code | [design: Modules And Dependencies](references/design.md#modules-and-dependencies) |
+| The same change keeps touching many places, or each fix adds another flag, state or caller rule | [design: Pressure Signals](references/design.md#pressure-signals) |
+| Behavior-preserving cleanup, refactoring or deletion is the agreed result | [simplify](references/simplify.md) |
+| A failure with no known cause, or two fixes that did not hold | [diagnose](references/diagnose.md) |
+| Moving users, data or traffic to a replacement, or removing an old path | [migration](references/migration.md) |
+| Adding edge-case handling, or a comment that explains why | [code practices](references/code-practices.md) |
+| Designing or changing a test | [Test Design](../verify-work/references/test-design.md) |
+| Choosing the checks that will show the change works, reproducing the problem before a fix, running the existing tests before and after, what a check shows, or a claim beyond its evidence | [Verify Work](../verify-work/SKILL.md) |
+| An empirical question to answer before building on it | Discuss Work's [learning action](../discuss-work/references/learning-action.md) |
+| A choice that is the user's, or a step the agreement does not cover | [Discuss Work](../discuss-work/SKILL.md) |
+| Committing, pushing, merging, releasing or deploying | [Deliver Work](../deliver-work/SKILL.md) |
 
-Use [Discuss](../discuss/SKILL.md) when outcome or material approach alternatives need reconsideration, [Decision Gate](../decision-gate/SKILL.md) for one blocking user-owned choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unsupported.
+## Rules
 
-## Gather Enough Context For This Unit
+- Stay inside the work agreement; an agreement to return a plan does not cover production edits. Take a new requirement, evidence boundary or other user-owned choice to Discuss Work before adopting it.
+- Never cross a selected Checkpoint while it is due and unresolved; Track Work names its owner.
+- Never rewrite a Spec, Plan, policy or acceptance criterion to make the implementation pass.
+- Never encode a guess for consequential behavior nobody defined: ask through Discuss Work, or, when no one can answer, take what matches existing behavior and is easiest to reverse, and report it.
+- When a Working Record exists, record the Current Slice through Track Work before its first effect.
+- Never promote exploratory code into production or invent acceptance.
 
-Choose the next coherent result, then identify what is missing to implement and check it. Reuse current supported sources; inspect only the live boundaries whose freshness matters.
+## Read The Request
 
-Find the relevant mechanism, callers, contracts, and observing seam before changing them. Do not begin substantial implementation from a guessed API, ownership boundary, or failure cause. Do not read every file or settle every later Slice merely to avoid all uncertainty.
+Goal: before the first edit, you know every separate ask, what the requester saw, and what must stay true.
 
-Readiness means you can explain what will change, why it should produce the accepted result, and how the result will be checked. It does not require knowing every line or helper in advance. If an unfamiliar fixture or observing stage could invalidate substantial dependent work, establish that observer first through a bounded investigation. Reuse adequate fixtures; do not make a separate prototype mandatory.
+List three layers:
 
-Before substantial implementation, read [Design for Depth](../design-for-depth/SKILL.md) and use its Implementation Decisions method when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Reuse applicable design decisions already supplied; distinguish required constraints, suggested mechanisms, and local freedom. A reference to a design is not enough when its relevant content is unavailable. Resolve the consequential unknown, not every future coding detail.
+- **Explicit asks:** each separate thing to do.
+- **Observations:** what the requester saw, often with numbers ("takes 2.3 s", "only after a restart", "sometimes"). They are facts about the real system; "sometimes" names a condition to find.
+- **Implied requirements:** what must stay true although nobody wrote it down. Check, for the thing you change:
+  - data the old code wrote (records, files, keys, cache entries) stays readable;
+  - every way users or code reach this behavior (commands, shortcuts, routes, jobs, startup, retries) keeps working;
+  - other readers of the output (formats, field names, order) still get what they rely on;
+  - the opposite case still works ("never include X" still includes everything that is not X);
+  - stated properties ("only when", "exactly once", "never") hold over all inputs, not only the example.
 
-Use [Action Selection](../action-selection/SKILL.md) when choosing the next source, observer, or effect is uncertain, broad, or repetitive. Stop gathering when the current unit is sufficiently supported. A mechanical read of a known caller or signature can remain inside execution; discovering an invalidated mechanism requires re-entry before dependent edits.
+The request fixes **what** must be true; **how** is yours, to change when evidence says so. Do not let your first approach redefine the requirement.
 
-When specialized guidance is needed, read [Domain Skill Composition](../workflow/references/domain-skill-composition.md). Before writing or changing code, read [Code Practices](references/code-practices.md). Before designing or materially changing a behavior check, read [Test Design](../verify-work/references/test-design.md); choose its oracle from accepted behavior rather than the implementation.
+When the requester suggests how, check its preconditions against the actual state first (`git status`, what gets built or deployed, what else touches the same files). If they do not hold, keep the goal, adjust the approach, and say why.
 
-## Keep The Unit Coherent
+Each choice these layers leave open for the user goes in Discuss Work's decision list; when no one can answer it (a routed assignment, an unattended run), take what matches existing behavior and is easiest to reverse, and report it. Before adding something unrequested (a dependency, a stored field, an option), ask whether the outcome needs it or only your approach does.
 
-A bounded action produces one useful execution or learning result with a checkable claim. It may contain several files, tools, edits, and checks. Do not fragment it by command, file, test, or method change.
-
-Choose work that can be understood, executed, checked, and corrected with a manageable working set. Split when dependencies, uncertainty, or distinct outcomes make one attempt unreliable; retain enough understanding of later constraints to avoid an obvious dead end.
-
-When a Working Record exists, use [Track Work](../track-work/SKILL.md) for recovery and write-ahead Current Slice state before Slice execution. Preserve useful provisional remaining work and dependencies through its existing fields. Do not create memory for a short direct result merely because execution began.
-
-Read [Execute Work Edges](references/execute-work-edges.md) when resuming uncertain prior work, changing a Slice boundary, reaching a selected checkpoint, or exposing separately controlled follow-on work.
+## Establish The Execution Basis
 
-## Execute Through One Suitable Method
+Goal: before the first effect, you know what is agreed, how you will get there, and what will show it worked.
 
-Implement the supported approach directly when the outcome and mechanism are understood. Unfamiliar work may need preparation first; it does not automatically require a separate prototype or a test-first implementation sequence.
+- **Outcome:** the agreed result, its constraints and non-goals, and where you stop.
+- **Route:** the main steps, their order, and which depend on feedback. For substantial dependent work, forecast internally which changes belong together and the earliest observation that could invalidate the rest.
+- **Evidence:** the checks that could disagree with a wrong result, on the user's path.
 
-Use one primary method at a time:
+Before the first production change, gather what the route's predictable steps will use (sources, callers, contracts, conventions, code to copy), with the queries in Find What The Change Touches, below: [touch-map](scripts/touch-map.mjs) (`node <execute-work-directory>/scripts/touch-map.mjs --symbol <name> --file <path>`) runs them as capped, labelled blocks (entry points, readers, writers, scheduled code, covering tests, and the developer docs covering each file), each saying what it did not search. Never start substantial work from a guessed API, owner or cause. Stop when what remains can only be learned by doing the work, such as a test result or the user's reaction to a draft, and adapt the route to that feedback. Reading files no step needs, or collecting information because it may be useful later, is over-gathering; pausing for context the route could have predicted is under-gathering: aim for fewer low-value interactions, not fewer calls at any cost. When the work needs unexpectedly large context, return that need to the user rather than reading the whole dependency tree, citing the host's usage figures, never invented token counts. A small, well-understood change needs no separate pass. You are ready when you can say what will change, why it should work, and how it will be checked.
 
-- direct implementation for a supported change;
-- [Simplify Code](../simplify-code/SKILL.md) when behavior-preserving complexity reduction is the accepted outcome;
-- specialized domain guidance when the environment or risk needs it;
-- a bounded learning action when an empirical uncertainty must be resolved before production work.
+An agreement to fix a bug covers investigation before the remedy is known. Domain guidance, such as a framework or security skill, supplies method, never authority; load it for the concrete technology or risk, not for a keyword.
 
-Preserve accepted behavior, failure semantics, repository conventions, and source truth. Do not rewrite tests, Specs, Plans, policies, or acceptance merely to make implementation pass.
+### Find What The Change Touches
 
-Allow local choices of helpers, editing order, and focused checks while the agreed result and effects remain unchanged. Handle edge cases required by accepted behavior, direct evidence, or material safety; return undefined consequential behavior rather than encode a guess.
+Consequences are hard to imagine and easy to query. Name what you are changing in one line, then query each of these and write every result down:
 
-For an unfamiliar design boundary that could invalidate later work, establish its first coherent implementation and distinguishing observation before dependent expansion. Compare the actual ownership, identity, ordering, and failure behavior with the selected design—not merely its proposed filenames. Preserve accepted predicates when a sketch proves wrong; stop dependent effects and resolve the affected mechanism through the current owner. Supported local improvements need no automatic handback or separate review.
+```bash
+echo '--- entry points'; grep -rn 'thing(' src | head -20
+echo '--- readers of the state'; grep -rn 'state_field' src | head -20
+echo '--- old data'; grep -rn 'write.*state_field' src | head
+echo '--- concurrent or scheduled'; grep -rn 'async\|schedule' src | head
+```
 
-## Execute A Bounded Learning Action
+For each line, write your decision next to it and name the thing: it changes too, because the request's goal needs it, or its users must still get exactly what they get now. The request not mentioning something is no reason to leave it out. Put the change where the behavior is owned, even when many callers share that code: keep callers correct by checking each, not by avoiding the shared code. Read the tests that cover that code before editing; they are the contract.
 
-Consume the declared question, observer, permitted effects, expected evidence, and return condition. If they are insufficient for safe execution, establish the missing basis through the requesting owner before acting. Do not assume Discuss was previously used or repeat framing that is already adequate.
+## Work One Method At A Time
 
-Build and run only what the observation needs. Correct an understood local observer defect within scope. Before adding scaffolding or a dependency, check whether it serves the current observation or implements a future product. Return before materially expanding effects or pursuing a different question.
+Goal: the agreed result, by the simplest method that fits, with accepted behavior intact.
 
-Stop when the question is answered or the observing limit is reached. Report support, contradiction, inconclusive evidence, or unavailable evidence honestly; do not keep polishing the prototype to manufacture a favorable result.
+Work in steps that each produce one checkable result, not one per command or file; [Track Work](../track-work/SKILL.md) owns how Slices are sized and recorded. Use one primary method at a time: direct implementation when the outcome and mechanism are understood, one routed reference when its situation holds, or a bounded learning action when an empirical question must be answered first. Name things for what they mean in the domain, and make invariants and failure behavior explicit in code, types or tests.
 
-Return evidence, limits, exploratory artifacts, and residual effects to the owner that asked the question, following the agreed artifact disposition. Do not silently promote exploratory code into production, invent acceptance, or claim unobserved integration. The receiving owner assesses what the finding changes and which next action is supported and authorized.
+For one mechanical edit across many sites, edit the first site by hand, then write a script or codemod; run it on that site's original state and diff against your hand edit until they match, then run it everywhere. Keep the script in the task's scratch location and name it in the report. Edit by hand when the sites are few or each needs its own decision.
 
 ## Re-enter When The Basis Changes
 
-Do not continue merely because implementation has begun.
+Goal: stop building on a basis that no longer holds, and go back only as far as the change requires.
+
+| What changed | Go to |
+| --- | --- |
+| A clear local defect with a supported remedy | Correct it in the same action |
+| The mechanism is invalidated, the outcome is not | Stop dependent edits; re-establish the approach |
+| A failure with no known cause, or two fixes that did not hold | [diagnose](references/diagnose.md), after Diagnose Before Fixing, below |
+| A claim exceeds its evidence | Verify Work, before fixing anything |
+| Accepted content, such as a Spec, Plan or Decision, changed | Its owner; reconcile the Working Record before dependent use |
+| A choice that is the user's | Discuss Work |
 
-- Clear local defect and supported remedy -> correct within the same action.
-- Required outcome clear but mechanism invalidated -> stop dependent edits and re-establish the approach.
-- Failure cause unclear or correction repeats -> Diagnose Failure before another patch.
-- Expected behavior or acceptance unsettled -> Discuss or Decision Gate.
-- New requirement, scope, compatibility, persistence, evidence, or user-facing return boundary -> Workflow before adopting it.
+Do not continue merely because implementation has begun. Before chasing a prerequisite, ask whether the agreed outcome needs it or only your current approach does; a failed approach does not prove a host change or stronger guarantee is necessary. Keep unaffected changes and contradicting evidence. Rerunning a check after the state changed, or polling an operation still producing its result, is not the repetition Diagnose Before Fixing stops.
 
-Before pursuing a prerequisite, distinguish what the accepted outcome requires from what the current approach happens to need. Choose the smallest supported remedy preserving acceptance. A failed approach does not prove that a host change or stronger guarantee is necessary.
+### Diagnose Before Fixing
 
-When corrections keep adding caller coordination, public states, flags, retries, test-only seams, or recovery rules, stop the patch stream. Diagnose the cause; use [Design for Depth](../design-for-depth/SKILL.md) when direct evidence establishes structural pressure. Do not use that lens to broaden ordinary local work.
+A plausible line of code is a hypothesis, not a cause: before fixing it, find an observation that would come out differently if it were wrong. The explanation must cover the whole symptom: the "sometimes", the size, the timing.
 
-Preserve unaffected changes and contradictory evidence. An optional improvement is not unfinished work.
+When your last two actions did not change what you believe, stop repeating them. Change the question ("which code runs between the input and the wrong value?"), change the kind of observation (run it if reading failed; read the producer if running failed), or check your cheapest assumption (did the build run? does the test import what you think?). Two failed fixes mean the diagnosis is wrong.
 
-## Verify And Self-Review The Result
+## Check, Then Continue Or Return
 
-Check at the boundary where a result will be accepted or used—not after every edit or command.
+Goal: the result is supported where it will be used, and the report says exactly what exists.
 
-1. Run the covered focused checks through the actual behavior or artifact boundary.
-2. Use [Verify Work](../verify-work/SKILL.md) to classify what the observations support and what remains unverified.
-3. Once evidence initially supports the result, use [Review Work](../review-work/SKILL.md) for silent self-review of concrete work. Guiding artifacts use their owning artifact-review route.
-4. Correct a supported local defect within authority, then rerun affected evidence and affected review lenses once.
-5. Route unresolved or repeated failure rather than iterating blindly. Distinguish a code defect from an invalid observer, stale evidence, or a misunderstood assignment before selecting another correction.
+Check where the result will be accepted or used, not after every edit. Use Verify Work for what the observations support, then Review Your Own Change, below, with [Review Work](../review-work/SKILL.md) for its lenses. Before you report, run [self-review](scripts/self-review.mjs) (`node <execute-work-directory>/scripts/self-review.mjs --base <ref> [--requirements <file>] [--test-command <command>]`) and read its report: status, diff stat, every changed existing test or fixture with its hunk, each new test and whether it fails on the base, per requirement whether its check ran after the last edit (record each check with its `check --id R<n>` command), and the feature files covering the change with whether each was driven since (drive those through Verify Work). Correct a supported local defect and rerun the affected checks once; route a repeated failure instead of iterating.
 
-A green check proves only its exercised assertions; a source read does not prove runtime behavior. Tests may be written before or after implementation as appropriate, without a formal test-first loop or invented earlier failure. Review judges suitability without replacing evidence. Evidence gaps in required behavior remain visible; optional stronger claims may be qualified instead of becoming extra work.
+If the result makes existing documentation untrue, correcting it is part of this work: use [Write Docs](../write-docs/SKILL.md). New documentation still needs a request.
 
-Independent review is separately selected. A self-review finding does not require a reviewer, and a reviewer suggestion does not authorize another change.
+Before each continuation, ask whether the next change meets an agreed requirement, repairs a demonstrated defect, or only adds an optional guarantee; an optional improvement is not unfinished work. Continue while the next step serves the same outcome and stays covered, starting a distinct Slice the agreement covers through Track Work without waiting for the user; a passing check is not the endpoint.
 
-## Continue Or Return
+Stop at the agreed return condition or an uncovered consequential boundary, and report as Report A Finished Change says, accounting for any edit made after the last check.
 
-Continue within the Slice while the next action serves the same outcome, remains covered, and can still be checked coherently. A method change, correction, or verification run does not create or close a Slice.
+### Review Your Own Change
 
-When durable memory exists, preserve only material changes to understanding, dependencies, scope, evidence, blockers, and the next useful action. Before context loss, record truthful partial state rather than rushing to completion. Resume only after required reconstruction and relevant live-state reconciliation.
+Before you report, read the actual change, not your memory of it: `git status`, `git diff`. Does it do every item on your list and nothing more? Do callers of what you changed still work (rerun the queries)? Did the check behind each requirement run after the last edit that could change its result? Any leftover debug output or scratch files? Fix what you find, recheck what that affects, and stop.
 
-Return to Workflow when a distinct Slice is ready, a selected checkpoint is due, the agreement changes, or no useful covered continuation remains. Workflow can select another already-authorized Slice without asking the user again. Internal method returns and delegation handbacks are not the user-facing endpoint.
+### Report A Finished Change
 
-Stop at the agreed return condition or an uncovered consequential boundary. Do not add cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch merely because it would be useful.
+When you finish a code change, end with:
 
-Construct the report from inspected resulting files, assertions, and outputs—not requested changes phrased as accomplishments. Distinguish implemented, checked, and still unsupported properties. Account for relevant edits after the checks; do not pair a fresh pass with superseded code or test captures. Reuse applicable evidence and report missing bodies or cases explicitly. A completed action is not automatically a completed Slice, task, or delivery.
+1. **The cause and the change**, citing `file:line`.
+2. **Each requirement**, including every stated one from a request, assignment or note, with the output showing it holds:
+   ```text
+   R1 <requirement> — observed: <command> → <result>
+   R2 <requirement> — not verified: <why>
+   ```
+3. **Choices the user has not seen** from the decision list, **what you did not verify**, and anything you noticed but did not change.

package/skills/execute-work/references/code-practices.md

@@ -1,47 +1,8 @@
 # Code Practices
 
-Read this before a bounded action writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
+Read this before adding edge-case handling or a comment that explains why. The repository's own conventions come first.
 
-## Make Intent Legible
-
-- Use names that express domain meaning rather than implementation trivia.
-- Keep behavior, state, and policy near the code that owns them.
-- Prefer the smallest coherent change over speculative abstraction or broad cleanup.
-- Make important invariants and failure behavior explicit in code, types, tests, or narrow comments.
-- Add a dependency, fallback, flag, state, or extension point only for accepted behavior or observed pressure.
-
-Clear code explains what happens. Comments preserve important context the code cannot express safely.
-
-## Comment Non-Obvious Why
-
-Comment when a future reader could reasonably make a harmful change without knowing:
-
-- an invariant, ordering, concurrency, precision, security, or compatibility constraint;
-- why an apparently simpler approach is wrong;
-- an external limitation or deliberate workaround;
-- why an obvious alternative was rejected;
-- why temporary behavior exists and what permits its removal.
-
-Do not:
-
-- narrate clear statements or control flow;
-- preserve comments that no longer match the code;
-- record broad architecture history inline;
-- write `TODO: fix later` without a real reason or exit condition.
-
-Put task status and future work in the Working Record or issue tracker. Put broad durable rationale in a Spec, decision record, or ADR. Leave only the local explanation needed to change the code safely.
-
-```ts
-// Bad: repeats the code.
-count += 1; // Increment count
-
-// Good: explains a non-obvious constraint.
-// Keep two passes: pass 2 consumes offsets frozen by pass 1.
-runFirstPass();
-runSecondPass();
-```
-
-For temporary behavior, name the actual constraint and removal condition. Link an existing issue when one exists; do not invent tracking metadata.
+This reference is judgment: adapt it to the work. Its binding statements restate [Execute Work](../SKILL.md) Rules.
 
 ## Handle Edge Cases By Evidence
 
@@ -50,12 +11,12 @@ Before adding behavior for an edge case, ask:
 1. Is it required by accepted behavior or a settled failure contract?
 2. Has it been observed or shown reachable at the supported boundary?
 3. Could ignoring it cause material safety, data, security, compatibility, or user harm?
-4. Is the expected result defined and inside the accepted work?
+4. Is the expected result defined and inside the agreed work?
 
 Then act proportionately:
 
 - **Required or observed, with defined behavior:** implement the smallest complete behavior and test the relevant boundary.
-- **Material but undefined:** stop and return the missing behavior decision to [Workflow](../../workflow/SKILL.md).
+- **Material but undefined:** stop and settle the missing behavior through [Discuss Work](../../discuss-work/SKILL.md).
 - **Plausible but unsupported:** gather evidence; do not add speculative handling.
 - **Useful but optional:** report or defer it as separate work.
 - **Purely hypothetical:** leave it alone.
@@ -66,13 +27,30 @@ API contract permits a missing value and defines the result
 
 "What if this is null?" with no requirement or reachable path
 -> do not add a null branch; classify the concern first
-
-Each correction reveals another related state or flag
--> stop patching; diagnose the shared contract, cause, or ownership
 ```
 
-Prefer an explicit invariant or clear failure over invented retry, fallback, recovery, or compatibility behavior. Handling an edge case creates a contract and future maintenance cost.
+Prefer an explicit invariant or a clear failure over invented retry, fallback, recovery, or compatibility behavior. Handling an edge case creates a contract and a future maintenance cost.
+
+## Comment Non-Obvious Why
+
+Comment when a future reader could reasonably make a harmful change without knowing:
 
-## Stop When The Action Is Supported
+- an invariant, ordering, concurrency, precision, security, or compatibility constraint;
+- why an apparently simpler approach is wrong;
+- an external limitation or deliberate workaround;
+- why an obvious alternative was rejected;
+- why temporary behavior exists and what permits its removal.
 
-Once the accepted result is supported, comments are accurate, and no material self-review issue remains, stop. Possible polish, unrelated cleanup, and imagined resilience are not unfinished work. They require new evidence or another accepted bounded action.
+Do not narrate clear statements or control flow, keep comments that no longer match the code, record architecture history inline, or write `TODO: fix later` without a real reason or exit condition. For temporary behavior, name the actual constraint and removal condition, and link an existing issue when there is one; do not invent tracking metadata.
+
+Put task status and future work in the Working Record or issue tracker, how the code works and why in the developer docs ([Write Docs](../../write-docs/SKILL.md)), and a hard-to-reverse choice in a decision record. Leave in the code only the local explanation needed to change it safely.
+
+```ts
+// Bad: repeats the code.
+count += 1; // Increment count
+
+// Good: explains a non-obvious constraint.
+// Keep two passes: pass 2 consumes offsets frozen by pass 1.
+runFirstPass();
+runSecondPass();
+```