j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan
deepworkplan
VerifiedDeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready.
guide/authoring.md
View on GitHub# DeepWorkPlan Guide — Authoring Plans and Task Files
> Part of the DeepWorkPlan methodology guide. The routing index is
> [`GUIDE.md`](GUIDE.md); read only the guide files your flow names.
## 4. Plan-Level README Structure (`{PLAN_NAME}/README.md`)
Each plan folder must have a `README.md` that serves as the **index and control center** for the deep-work session.
### 4.1. Required sections
A plan README must contain:
1. **Plan Title and Goal**
2. **Context**
3. **Plan Variables** (optional — branch, target env, custom variables; high-signal example rows in §4.2)
4. **Global Constraints / Guidelines**
5. **Task List (with links to task files)**
6. **Execution Rules for the Agent**
7. **Skills & Agents Used in This Plan** (see section 11)
8. **Plan Status / Notes**
9. **Analysis Outputs** (reports generated during execution)
10. **Quick Note:** Reference to PROMPTS.md file for ready-to-use prompts
### 4.2. Example structure
```markdown
# Plan: {Human-readable Plan Title}
## 1. Goal
Short description of the overall objective of this plan.
Example:
- Expand UI showcase docs and components.
- Refactor the Smart Check-ins engine for better maintainability.
- Improve test coverage and documentation for feature X.
## 2. Context
Provide relevant context:
- Tech stack (e.g., Node.js 20.x, TypeScript 5.9.2, AWS Lambda, Serverless Framework, DynamoDB, OpenAI API).
- Where the code lives (e.g., `src/functions/botFlow/`, `src/common/`).
- Any important dependencies or constraints.
## Plan Variables (optional)
Custom rows are always allowed. High-signal rows proven by long-horizon plans
— add only the rows this plan needs, never as a ritual:
| Variable | Value |
|----------|-------|
| Branch | {branch_name} |
| Target environment | {env} |
| Rigor | {standard / deep} — the tier and why |
| Primary scope | {the one surface this plan must not miss} |
| Evidence bar | {what counts as done — named artifacts, mirrors, verified states} |
| Quality commands | {the repo's lint / type-check / test invocations} |
| Forbidden | {hard exclusions — files never touched, patterns never introduced} |
| {custom_variable} | {value} |
## 3. Global Guidelines
Some examples:
- Always work in a feature branch, never directly on `main`.
- Use small, incremental, well-described commits.
- Run tests (`npm run test`) and linters (`npm run eslint:check`) as specified in each task.
- Follow TypeScript strict mode with explicit type annotations.
- Use Logger from `src/common/logger.ts` (NEVER `console.*`).
- Test files must use `*.spec.ts` naming convention.
- Follow import order: Node.js native → third-party → internal → types.
- Prefer clear, maintainable code over micro-optimizations.
## 4. Task List & Links
The agent must execute tasks **in order** and **one at a time**.
- [ ] Task 1: Add Discord message handler (keeps its integration docs current in-task)
See: [1.task_add_discord_message_handler.md](./1.task_add_discord_message_handler.md)
- [ ] Task 2: Add integration tests for Discord handler (registers the new gate in `docs/TESTING_GUIDE.md` in-task)
See: [2.task_add_integration_tests_for_discord.md](./2.task_add_integration_tests_for_discord.md)
- [ ] Task 3: Restructure Discord integration documentation (substantial docs surface — its own task by design, not a catch-up)
See: [3.task_update_discord_docs.md](./3.task_update_discord_docs.md)
> **Mandatory final task:** Every plan ends with a single **Final Review** (security pass over the accumulated diff, full validation of the final state, reconciliation of the skills ledger). Skills decisions are made inside each task as it completes; the Executive Report is **optional** and offered once at completion. The Final Review is auto-generated by `/dwp-create`. (Plans created under earlier versions end with three final tasks and are executed under their own shape.)
> **Agent rule:** Always work on the first unchecked `[ ]` task, and only move to the next after fully completing it.
## 5. Execution Rules for the Agent
- Work strictly in the order defined in the Task List.
- Focus on **one task file at a time**.
- Do not skip or reorder tasks.
- For each task:
- Open the corresponding `N.task_*.md`.
- Follow the detailed instructions carefully.
- Run validations.
- **⚠️ MANDATORY: Mark the task as completed:**
- **UPDATE this README task list `[ ] → [x]`** (CRITICAL!)
- **UPDATE the Plan Status section** (completed count)
- **UPDATE the task file's completion / log section**
- Commit changes before moving to the next task.
- Stop and log any blocking issue or failing validation.
> **IMPORTANT:** Failing to mark tasks as completed will break resume functionality and cause repeated work!
## 6. Skills & Agents Used in This Plan
| Task | Skill/Agent | File Path | Purpose |
|------|-------------|-----------|---------|
| Task N | `/skill-name` skill | `.agents/skills/skill-name/SKILL.md` | Brief purpose |
| Task M | `agent-name` agent | `.agents/agents/agent-name.md` | Brief purpose |
> **Note:** Skills provide step-by-step procedures. Agents provide validation checklists.
> See `.agents/docs/skills_agents_catalog.md` for the full registry.
> (`.claude/` and `.cursor/` are symlinks to `.agents/` — all three paths resolve identically.)
## 7. Plan Status / Notes
- Current status:
- Example: "In progress, Task 2"
- Relevant notes or decisions that affect the whole plan.
## 8. Analysis Outputs
Reports and artifacts generated during plan execution are stored in `analysis_results/`.
| Output | Generated By | Description |
|--------|-------------|-------------|
| `SKILLS_CANDIDATES.md` | Every task, at completion | Task-local skills decisions by stable ID (`T{task}-{seq}`); reconciled by the Final Review |
| `SECURITY_REVIEW.md` | Task N (Final Review) | Security pass over the plan's changes; verifies `docs/SECURITY.md` is current; records the final-state validation |
| `EXECUTIVE_REPORT.md` | Optional — on request after completion | Comprehensive summary of all work done (unchanged content; generated only when asked) |
## 9. Quick Reference
**Need prompts for this plan?** See [PROMPTS.md](./PROMPTS.md) for ready-to-use copy-paste prompts to execute, resume, or check this plan.
```
---
### 4.3. Stage Gates (optional — long Full plans only)
A **Stage Gate** is a named mid-plan checkpoint: one row of an optional README
table saying what must be true — with evidence — at a task boundary. Long
plans used them to stay steerable (the executed corpus ran 35–103-task plans
this way); small plans do not need them.
**When to author:** only for a **Full plan with 20 or more task files** (well
past the executed-plan median of ~13). A **Lite plan never carries Stage
Gates**, and a shorter Full plan **omits them by default** — a shorter plan
may still add one or two deliberately when a phase boundary genuinely needs
named evidence; that is judgment, not ritual.
**Shape (from executed long-horizon plans):**
| Gate | After task | Evidence required |
|------|------------|-------------------|
| {Stage name} | {N} | {named artifact or observation proving the stage's outcome} |
Author **one gate per coherent phase** of the plan (a direction gate after the
foundational tasks, a baseline gate, a release-readiness gate …), never one
per task. Each row names evidence the plan's own task outputs already produce
(an `analysis_results/` artifact, a passing gate log, a mirrored surface) —
never evidence invented for the checkpoint.
**Execution semantics.** A Stage Gate is an **always-sequential barrier**: when
execution reaches the row's task boundary, every task up to that row — across
all parallel groups in a parallel plan — is complete and the row's named
evidence is recorded before the next stage starts. Place the table adjacent to
the Execution Rules section, so the executing agent reads it with the rules it
already follows. Stage Gates are intermediate checkpoints only: the **Final
Review remains the single terminal task**, is never listed as a stage-gate
row, and the last stage gate lands before it.
---
## 5. Task File Structure (`N.task_{task_title}.md`)
Each task file is a **self-contained deep-work prompt** for a single task.
The agent must be able to read **only this file**, understand exactly what to do, and execute it to completion.
Every task carries **one objective** (`spec/DWP_SPECIFICATION.md` §6.4): it may perform several steps that serve that objective, and must never bundle several objectives — prefer N one-objective tasks over fewer multi-objective ones.
### 5.1. Required and optional sections
Each `N.task_{task_title}.md` must have the following sections. The spec's canonical anatomy is **ten** required sections (`spec/DWP_SPECIFICATION.md` §5); the list below expands them to twelve entries by naming the two optional sections (Rollback, and Execution Checklist shown separately from Completion & Log) (optional sections are marked):
1. **Title**
2. **Context**
3. **Read Before Starting** _(optional — list prior task logs to review)_
4. **Goal**
5. **Touched Surface** _(required for any behavior-changing task — planned and reconciled actual paths, affected consumers, risk class, the test mapping used, the selected gate and its reason; `not applicable — <reason>` for pure prose/research tasks; `spec/DWP_SPECIFICATION.md` §5.0.2)_
6. **Instructions** _(with re-anchoring instruction as first line — recommended)_
7. **Acceptance Criteria**
8. **Outputs** _(optional — declare what this task produces)_
9. **Validation**
10. **Rollback** _(optional — instructions if task fails)_
11. **Execution Checklist (step-by-step)**
12. **Completion & Log (filled by the agent)**
### 5.2. Example template
> **Section headings and field labels are load-bearing, not styling.** The
> conformance checker finds each field by parsing them
> (`verify/plan_contract.py`), and this applies to **Full task files exactly as
> it does to Lite inline records**. A heading is `## Goal` or `## 1. Goal`,
> optionally with a parenthetical suffix (`## 11. Completion & Log (filled by
> the agent)`), and nothing else on the line. An inline label is `**Goal:**` or
> `**Goal**` — those two forms. A decorative variant such as `**Goal.**`, or a
> heading that continues past the section name, makes the field invisible to
> the checker: the plan then fails conformance with one "lacks Goal" issue per
> task for zero content reasons.
````markdown
# Task {N}: {Task Title}
## 1. Context
Explain clearly:
- Which part of the codebase this affects.
- Where the relevant files are.
- Any existing patterns or conventions to follow.
- Links or references to design docs if needed.
## 2. Read Before Starting (optional)
- Task {X} Completion & Log: {what to extract}
- Task {Y} Completion & Log: {what to extract}
## 3. Goal
A concise description of what this task must achieve.
Example:
- "Add a Discord message handler following the platform integration pattern."
- "Add integration tests for the Discord handler covering cases A, B, and C."
## 4. Touched Surface
Required for any task that changes behavior (code, configuration, schemas, templates, fixtures, migrations, generated inputs, agent instructions). Pure prose or research tasks write `not applicable — <reason>`.
- **Planned surface:** {paths / modules / packages this task intends to change}
- **Actual surface (reconciled after editing):** {from the real diff — staged, unstaged, generated}
- **Affected consumers:** {modules, templates, services that import / load / render the surface — from `docs/TESTING_GUIDE.md`'s mapping or the repo's affected-test tooling; say so if unknown}
- **Risk class:** isolated | seam | shared/core | unknown
- **Test mapping used:** {convention, marker, or affected-tests command; verified for this repo? yes/no}
- **Selected gate and reason:** {the Validation commands below, and one line each on why they cover the surface — or why the full-suite fallback was taken}
## 5. Instructions
> **Before starting:** Re-read the plan README section 1 (Goal) to ensure this task's work aligns with the overall objective.
Detailed, actionable instructions for this **single** task.
Guidelines:
- Specify directories and filenames.
- Mention patterns to reuse or avoid.
- Provide detailed prompts if necessary.
- Clarify what _not_ to change, if important.
Example:
- Implement a new handler at `src/functions/botFlow/handlers/discord/messageHandler.ts`.
- Follow the handler pattern defined in `docs/ARCHITECTURE.md`.
- Use TypeScript strict mode with explicit type annotations.
- Ensure proper error handling and logging using Logger.
## 6. Acceptance Criteria
Explicit conditions for considering this task **done**.
Examples:
- All required functionality is implemented.
- Code matches the patterns in `docs/ARCHITECTURE.md`.
- No TypeScript errors are introduced.
- New or changed behavior is covered by automated tests added or updated in this task (see §5.3).
- All tests pass (`npm run test`).
- ESLint checks pass (`npm run eslint:check`).
- Naming and structure follow existing conventions in `docs/STANDARDS.md`.
## 7. Outputs (optional)
- `analysis_results/{FILE_NAME}.md` — {description}
- Updated: `{file_path}` — {what changed}
- Decision: {description} (see Completion & Log)
## 8. Validation
Commands that **must be executed and pass** before marking the task as completed.
Example:
```bash
# Selected from the Touched Surface, using this repo's documented patterns (docs/TESTING_GUIDE.md):
npm run test -- tests/unit/discord # tests of the changed module AND its affected consumers
npm run eslint:check -- src/functions/botFlow/handlers/discord
npm run typecheck # whole-project where that is the cheap default
# Fallback — no documented scoped invocation, or the surface is shared/core, config, schema or toolchain:
codecheck # the repo's full code-quality check
```
If any of these fail, the agent must **stop, log the issue, and not mark the task as complete**. A run that selects zero tests is not a pass — fix the selector or fall back.
**Note:** The `codecheck` command (from `docker/custom_commands.sh`) runs setup, automatic fixes, and tests in sequence; it is the fallback and the final-state gate, not the default per-task gate.
For a task that changes product behavior, Validation **must** run the tests **and** the lint/type-check/format checks selected from the task's Touched Surface, widening to the full suite when the change is shared/core or no scoped invocation is documented — see §5.3. The complete suite runs once more on the final state in the Final Review.
## 9. Rollback (optional)
If this task fails and cannot be resolved:
- {specific rollback instructions}
## 10. Execution Checklist
The agent must follow these steps sequentially:
- [ ] 1. Read this task file fully and understand the goal and constraints.
- [ ] 2. Inspect the current implementation / related files.
- [ ] 3. Implement the required changes.
- [ ] 4. Make the skills decision (§6.2) and the documentation decision (§5.5) — record both dispositions in the log below.
- [ ] 5. Run the validation commands listed above.
- [ ] 6. Review the diff and ensure it matches acceptance criteria.
- [ ] 7. Update the plan README to mark this task as `[x]` in the Task List.
- [ ] 8. Update PROGRESS.md with task summary.
- [ ] 9. Commit the changes referencing the plan: `git commit -m "type(scope): description - Task {N} of {PLAN_NAME}"`
- [ ] 10. **If the Dailybot addon is installed in this repo** (`.agents/skills/dailybot/`): send a progress report IF this task is independently significant (feature, fix, major refactor) — a standup-style *"Implemented [what] — [why it matters]."* Skip the step entirely when the addon is absent; never inject an addon step into a repo that has no addon. (non-blocking — continue if it fails)
- [ ] 11. Update the Log section below.
## 11. Completion & Log (filled by the agent)
The agent must append a short log here when the task is done (or blocked):
- **Status:** (completed / blocked / failed validation)
- **Timestamp:**
- **Summary of work:**
- **Files changed:**
- **Skills disposition:** (`none` / `update <existing>` / `create <name>` / `defer — <reason, owner>`)
- **Documentation decision:** (docs updated for the touched surface — list, or `not applicable — <reason>`)
- **Gate record:** (command, cwd, scope/reason, revision or fingerprint, result, evidence path)
- **Validation results:**
- **Notes / follow-ups:**
````
### 5.3. Test & Validation Discipline (MANDATORY)
Tests are a first-class part of the loop — they are what makes the code a Deep
Work Plan ships **reliable** and verifiable, not just "written". This discipline
applies on every plan, in addition to the per-task validation gates above:
- **New core functionality or changed behavior ⇒ tests.** When a task implements
new functionality or materially changes existing behavior, that task **MUST**
add or update automated tests covering the new/changed behavior (happy path +
meaningful edge/error cases), following the repo's test convention and coverage
expectation (`docs/TESTING_GUIDE.md`). Put it in the task's **Acceptance
Criteria** so it is checkable.
- **Run the right gate for the surface, not just the build.** A behavior-changing
task's **Validation** must run the repo's **tests** *and* its **lint /
type-check / format** checks, **selected from the task's Touched Surface**
(`spec/DWP_SPECIFICATION.md` §5.1): the tests of the changed behavior plus its
affected consumers for an isolated change; the integration/contract tests of the
seam for a seam change; a widening to transitive consumers or the **full** suite
for shared/core, configuration, schema, dependency or toolchain changes, and
whenever the impact cannot be bounded or no scoped invocation is documented
(e.g. `codecheck`, `npm run test -- <path> && npm run lint`, `pytest tests/<module>
&& ruff check`). Zero selected tests is never a pass. "It builds" / "the file
exists" is not a sufficient gate for a behavior change. The complete suite runs
on the **final state** in the Final Review (§5.1.3) — full validation is a
requirement on the end result, not a per-task ritual.
- **Unit-first, integration where it matters.** Build coverage from the base of
the pyramid: fast, deterministic unit tests of observable behavior and
meaningful boundaries (no I/O, no network), covering errors, edges and
regressions; integration or contract tests at the real seams the task changes
— added in that task, not deferred to the end; few, high-value end-to-end
tests. It is a default strategy, not a ratio or a quota — and it is what makes
scoped gates fast.
- **Keep existing tests green.** If a change breaks a test that covers the
affected code, update the test to reflect the intended new behavior. **Never**
delete, skip, or weaken a test just to make the gate pass.
- **Proportional, not bureaucratic.** Depth of testing scales with the size of the
change and the repo's maturity — a one-line fix is not a test suite. Pure docs /
config / research tasks are exempt from *creating* tests but still run the repo's
validation gate.
- **No toolchain? It was proposed at onboarding.** If the repo has no test/lint
setup, onboarding proposes one fit to the stack and records it in
`docs/TESTING_GUIDE.md` (`spec/DOCUMENTATION_STANDARD.md` §3.3). Plans then
execute against that — they do not silently skip validation.
> A plan that adds features but ships **zero** test changes is a smell: either the
> work was not behavior-changing, or the test discipline was skipped. Call it out
> in the Final Review's `SECURITY_REVIEW.md` and the completion report (and in the
> Executive Report if one is requested) rather than hiding it.
#### 5.3.1. Writing a gate that can fail
A gate is a hypothesis about the change until it has been seen to fail
(`spec/DWP_SPECIFICATION.md` §5.1.4):
- **Prove it can fail.** For a new or changed gate, record one failing run
against a seeded defect or the pre-change tree in the task log, then the
passing run. A test that passed on its first run is unproven, not good news.
- **No vacuous passes.** A missing binary, an empty input, zero files or tests
matched, an empty log or `|| true` is a failure. Write pipelines with
`set -o pipefail` (or check each status). In Bats on macOS's bash 3.2 a
failed `[[ … ]]` or a negated `! cmd` does not fail the test by itself:
end it with `|| false` or use `[ … ]`.
- **Exact output needs a sentinel.** `$(…)` strips trailing newlines, so compare
`"$(f x; printf s)"` with `$'y\ns'`: a function that drops or doubles its last
newline then fails.
- **Observed, not self-quoted.** A gate that greps text the agent wrote in the
same task is a structural guard; behavior needs a gate that runs the
behavior.
- **Pins are data.** Criteria and gates reference a pin *source* — a pins
file, "the latest release", a lockfile — never a literal tag in the
criterion text, so a pin move re-runs the gate without amending the
contract.
- **Declare the environment.** Name where the gate runs: a container wrapper
as a declared command class (`dck exec <service> -- <cmd>`), an explicit
working directory, `LC_ALL=C` where output is compared. A preflight checks
the environment before Task 1; an environment failure is a blocker, never a
pass and never blamed on the change.
- **Measure first.** Task 1 of a fix, an audit or an optimization verifies the
premise and the measuring tool; later tasks compare against the base branch,
not only a threshold.
### 5.4. Security Discipline (MANDATORY)
Security follows the same two-layer model as testing: woven into the tasks while
the work happens, plus the Final Review's security pass over the whole
plan at the end (`spec/DWP_SPECIFICATION.md` §6.1):
- **Risk-touching task ⇒ security criteria.** When a task touches auth, input
handling, secrets/config, network/file/shell surface, or dependencies, bake the
security expectations into its **Acceptance Criteria** (input validated, no
secret material anywhere in the diff — fixtures and docs included, auth checks
preserved), consistent with `docs/SECURITY.md`.
- **No secrets in any commit.** Before each per-task commit, confirm the diff
carries no credentials or secret material. A committed secret in a pushed
commit must be treated as leaked — rotate it, don't just remove it.
- **Substantial security work gets its own task — before the tests task.** Order
the plan implement → security hardening → comprehensive tests → docs: fixes
land before the tests encode the behavior, and each finding becomes a
regression test case instead of rework.
- **The final gate still runs.** Per-task discipline does not replace the
Final Review's security pass — that gate audits the full accumulated diff,
including what the tests and docs tasks themselves changed.
#### AI Diff Reviewer local pass (required — baseline since 2.3.0)
The Final Review's security pass runs the
[`ai-diff-reviewer` addon](../addons/ai-diff-reviewer/SKILL.md)'s local review
as a required step; `onboard` installs the reviewer (Phase 7a) unless declined
or unavailable. Degradation is honest, never silent: an absent
upstream skill or extension file is recorded as a `local reviewer not
installed` finding, carried into the completion report; installation belongs to
onboarding or an explicit addon invocation, and a local review invocation error produces a warning + record,
never a failed task (addon SPEC §6.1, §7).
Flow A needs no CI provider secret; an unset `CURSOR_API_KEY` (or other
provider secret) must not suppress the local pass — that secret is Flow B CI /
gate messaging only.
- **Detection.** `.agents/skills/ai-diff-reviewer/` present + an extension file
at one of the three recognized paths (in precedence order): `.review/extension.md`
> `.github/ai-diff-reviewer/extension.md` > `.github/ai-pr-reviewer/extension.md`
(pre-v1.5 back-compat).
- **Invocation.** Route to the upstream skill's parent default flow ("Review
my current branch" / `/ai-diff-reviewer`) — the local review is capability
#1 of the upstream skill's six-sub-skill router (parent + `generate-extension`
+ `setup` + `open-pr` + `apply-review` + `address-review`).
- **Output shape.** Verdict + findings table (columns: `#` / Severity / File /
Summary) + per-finding body + notes + recommendation. Shared `prompt.md` +
extension align methodology/severity with the CI Action at the same tag
(byte-identical prompts, enforced by upstream CI); under Flow B, CI round 2+
may be shorter via Iteration-Aware Review while the local pass stays full.
- **Integration.** Append the output to `analysis_results/SECURITY_REVIEW.md`
under a dedicated `## AI Diff Reviewer local review` heading — so a reader
sees the manual security-pass findings and the AI-augmented findings side by side.
- **Severity handling.** A **verified** `critical` (v3, BC-07) blocks completion
until fixed or explicitly accepted (existing SR contract; unverified critical
claims arrive as annotated warnings); `warning` and `info` are documented but
non-blocking. The reviewer's `.review/extension.md` (repo-tailored) shapes
what maps to which severity — this is the primary customization surface.
- **Optional Flow B post-CI companion.** When the repo runs the CI Action
(Flow B) AND the plan's PR has been pushed AND CI has posted its review,
the developer MAY invoke the upstream `apply-review` sub-skill from within
the same `execute` session to walk through CI-posted findings per-finding
(apply / defer / skip) with explicit consent. `apply-review` is read-only
by default; edits require per-finding yes; never commits or pushes. This
is an *available option* during `execute`, never a plan task file — the
addon MUST NOT insert an `apply-review` task (would violate the
single-Final-Review rule).
### 5.5. Documentation Discipline — Boy-Scout (MANDATORY)
Documentation follows the same two-layer model as testing and security: kept
current **inside the task that changes the surface**, plus a reconciliation
sweep in the Final Review (`spec/DWP_SPECIFICATION.md` §6.1; the normative
rules live in its §6.6). The documentation a repository ships **is** the
harness every future plan reads — documentation debt is context debt, and
every plan after this one pays interest on whatever this one leaves stale.
- **Registered-surface task ⇒ doc currency, in the same task.** A task that
changes behavior, structure, commands, configuration, or agent surface
**MUST**, in that same task, update the documentation that registers what
it touched: the gate/command registry (`docs/TESTING_GUIDE.md`), structure
docs, module or feature docs, the `AGENTS.md` index when a new top-level
surface appears. Put it in the task's **Acceptance Criteria** so it is
checkable.
- **The Touched Surface names the docs** — the *planned docs surface*
(`spec/DWP_SPECIFICATION.md` §5.0.2): a doc named in the plan but not
updated by the close of the task is a reconciliation miss, not a follow-up.
- **Proportional, not bureaucratic.** Pure-prose, config-comment, or research
tasks record `not applicable — <reason>`; a one-line fix updates at most a
one-line reference.
- **Substantial doc work gets its own task — placed with the work, never
after it** (ordered like the security discipline §5.4: the docs that
describe behavior land before the tests that encode it; neither is
deferred past the Final Review's sweep).
> A plan that changes registered surface but ships **zero** doc updates
> across all its tasks is a smell. The Final
> Review's documentation sweep reports it — it does not silently absorb it.
---
### Completion evidence in generated tasks
Every completion log includes its status, `Skills disposition:` and
`Documentation decision:`. Final Review uses the installed guarded finalization
helper; source/acceptance gates already ran before a terminal candidate is
validated. Its own receipt is not a prerequisite for its own check.
### Amendments in authored task records
Author every task's Completion & Log so a later amendment has somewhere honest
to land: `Status:`, `Skills disposition:`, `Documentation decision:` and the
`Gate record:` lines exist from creation, and nothing completed is ever
rewritten — changes append. When scope or a criterion changes, the record is
the structured amendment from the refine contract (original criterion,
observed, disposition, reason, authority, affected tasks, evidence invalidated
and preserved); name the five evidence states exactly — a completed
investigation is not an executed criterion, an unexecuted scenario carries no
passing evidence, and a failed gate only closes when the same acceptance
intent passes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |