@winton979/task-cli 1.2.1 → 1.3.1

package/README.md

@@ -46,6 +46,8 @@ Compatible Grill Me implementations may also work.
 
 If no Grill Me compatible skill is installed, `task-fast`, `task-explore`, and `bug-explore` fall back to built-in clarification prompts.
 
+When `.ai/decisions/decisions.md` contains real entries, those skills should inspect it before finalizing a brief and pull in only the decisions that materially constrain the current task or bug.
+
 ---
 
 ## Usage
@@ -129,6 +131,7 @@ BUG_READY
 ### Other
 
 * decision-log
+* decision-sweep-weekly
 
 ---
 
@@ -153,6 +156,20 @@ BUG_READY
 
 ---
 
+## Weekly Decision Sweep
+
+Calling `/decision-log` after every task is easy to forget. As a lower-friction alternative, run `decision-sweep-weekly` once per week (Friday is a natural fit):
+
+```
+/decision-sweep-weekly
+```
+
+The skill scans archived task and bug briefs from the past 7 days, judges which ones contain a decision worth keeping (cross-task impact, rejected alternatives, counter-intuitive choices, externally driven calls, or instructive cancellations), drafts the entries, and waits for confirmation before appending to `.ai/decisions/decisions.md`.
+
+Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough; using both is fine.
+
+The decisions file is intentionally narrow. It is meant to hold durable project invariants and reusable constraints, not a running transcript of every local implementation choice.
+
 ## Philosophy
 
 Task CLI is intentionally lightweight.
@@ -167,6 +184,8 @@ Instead of maintaining large specifications, it focuses on:
 
 The goal is to improve quality without slowing down iteration speed.
 
+That decision history is meant to be selectively reusable. Explore and fast-path skills should consult it to avoid violating existing project decisions, but only the parts that materially constrain the current work belong in the new brief.
+
 ## Compared with OpenSpec-Style Workflows
 
 Task CLI is designed as a lightweight alternative to heavier spec-driven systems such as OpenSpec.
@@ -223,7 +242,7 @@ task refresh
 This will:
 
 * keep `.ai/tasks`, `.ai/bugs`, and `.ai/decisions`
-* remove only these managed skills from `.claude/skills/` and `.codex/skills/`: `task-fast`, `task-explore`, `task-implement`, `task-review`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-review`, `bug-cancel`, `decision-log`
+* remove only these managed skills from `.claude/skills/` and `.codex/skills/`: `task-fast`, `task-explore`, `task-implement`, `task-review`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-review`, `bug-cancel`, `decision-log`, `decision-sweep-weekly`
 * reinstall the latest versions of those skills
 
 This avoids touching unrelated custom skills in the same project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Lightweight task workflow CLI for AI-assisted development",
   "license": "MIT",
   "type": "module",

package/src/init.js

@@ -19,6 +19,17 @@ const GRILL_ME_HINTS = [
   'grill me',
 ];
 
+const DECISIONS_READ_GUIDANCE = `Decision Intake
+
+Before finalizing the brief, inspect .ai/decisions/decisions.md if it exists and contains real entries beyond the title.
+
+Use it narrowly:
+
+* extract only decisions that materially constrain this task
+* ignore unrelated historical notes
+* treat the file as a source of durable project invariants, not as a second specification
+* if relevant decisions exist, summarize them briefly in Context or Constraints instead of copying them verbatim`;
+
 const SKILLS = {
   'task-fast': {
     name: 'task-fast',
@@ -37,18 +48,22 @@ Workflow
 
 1. If a Grill Me compatible skill is available in the current environment, use it for requirement clarification.
 2. If no Grill Me compatible skill is available, clarify the requirement yourself with focused questions just far enough to remove ambiguity.
-3. Create a concise task brief and save it to:
+3. Read the project code and conventions needed to avoid obvious conflicts.
+4. Read .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+5. Create a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-4. Show the brief before coding.
-5. If the user does not object, implement immediately.
-6. Verify the result against the acceptance criteria.
-7. Archive the brief automatically by moving it to:
+6. Show the brief before coding.
+7. If the user does not object, implement immediately.
+8. Verify the result against the acceptance criteria.
+9. Archive the brief automatically by moving it to:
 
 .ai/tasks/archive/YYYY-MM-DD-task-name.md
 
-8. Summarize the outcome and any follow-up risks.
+10. Summarize the outcome and any follow-up risks.
+
+${DECISIONS_READ_GUIDANCE}
 
 Task Brief Format
 
@@ -105,11 +120,14 @@ Workflow
 3. Continue until the task is sufficiently understood.
 4. Do not write code.
 5. Do not create implementation details.
-6. Once the requirement is clear, generate a concise task brief and save it to:
+6. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+7. Once the requirement is clear, generate a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-7. Show the saved brief and stop.
+8. Show the saved brief and stop.
+
+${DECISIONS_READ_GUIDANCE}
 
 Task Brief Format
 
@@ -292,11 +310,14 @@ Rules
    * expected behavior
    * assumptions
 
-8. Once the bug is sufficiently understood, generate a brief and save it to:
+8. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain the observed behavior, expected behavior, or likely root cause.
+9. Once the bug is sufficiently understood, generate a brief and save it to:
 
 .ai/bugs/active/YYYY-MM-DD-bug-name.md
 
-9. Show the saved brief and stop.
+10. Show the saved brief and stop.
+
+${DECISIONS_READ_GUIDANCE}
 
 Bug Brief Format
 
@@ -456,6 +477,8 @@ Purpose
 
 Record important implementation decisions.
 
+Only record decisions that are likely to matter beyond a single task. Good candidates are durable constraints, architecture boundaries, rejected alternatives someone may retry later, externally forced choices, and intentional behavior that otherwise looks incorrect.
+
 Save Location
 
 .ai/decisions/decisions.md
@@ -485,6 +508,79 @@ Requirements
 * Maximum 10 lines per decision
 * Append only
 * Keep concise
+`,
+  },
+
+  'decision-sweep-weekly': {
+    name: 'decision-sweep-weekly',
+    description: 'Weekly sweep of recent task and bug briefs to decide which deserve a decision-log entry. Proposes entries for confirmation before appending.',
+    content: `---
+name: decision-sweep-weekly
+description: Weekly sweep of recent task and bug briefs to decide which deserve a decision-log entry. Proposes entries for confirmation before appending.
+user-invocable: true
+---
+
+Purpose
+
+Batch-review the past week of work and sediment only the decisions that outlive a single task. Replaces per-task reminders with one weekly pass.
+
+When to Run
+
+Run once per week, ideally on Friday. May also run ad-hoc after a busy stretch.
+
+Workflow
+
+1. Scan briefs created in the last 7 days under .ai/tasks/archive/ and .ai/bugs/archive/. Filter by filename date prefix YYYY-MM-DD. If a brief lacks a date prefix, fall back to filesystem mtime.
+2. For cancelled briefs in either archive, treat the abandonment itself as potential decision material.
+3. Evaluate each brief against the Sediment Conditions below.
+4. For each candidate, draft a decision entry using the four-section format.
+5. Present a single review list: every scanned brief with a verdict (write / skip / insufficient info), then the proposed drafts grouped at the end.
+6. Do NOT append anything yet. Wait for the user to confirm which drafts to keep, edit, or drop.
+7. Only after confirmation, append the approved entries to .ai/decisions/decisions.md, oldest first, under the matching YYYY-MM-DD section heading.
+8. Report what was appended and what was skipped.
+
+Sediment Conditions
+
+A brief becomes a decision entry if it satisfies any of:
+
+* Cross-task impact: the choice constrains how future tasks must be written.
+* A concrete alternative was rejected and someone could plausibly pick it later.
+* Counter-intuitive choice: code reads like an anti-pattern but is intentional.
+* Externally driven: compliance, performance, compatibility, or a third-party API limit forced the call.
+* A cancelled attempt whose failure is itself a useful conclusion.
+
+Skip Conditions
+
+* Affects only the implementation detail of one task.
+* A temporary or unsettled conclusion.
+* A bare fact with no decision behind it.
+
+Entry Format
+
+## YYYY-MM-DD
+
+### Problem
+
+What issue was encountered.
+
+### Decision
+
+What was chosen.
+
+### Reason
+
+Why this choice was made.
+
+### Alternatives Considered
+
+What alternatives were rejected.
+
+Requirements
+
+* Maximum 10 lines per decision
+* Append only
+* One date section per day; multiple decisions on the same day stack under the same heading
+* Never edit or delete prior entries
 `,
   },
 };
@@ -649,7 +745,8 @@ export function init(cwd, { fs, path, log }) {
   fast:  task-fast
   task:  task-explore -> task-implement -> task-review | task-cancel
   bug:   bug-explore -> bug-fix -> bug-review | bug-cancel
-  other: decision-log`);
+  other: decision-log
+  sweep: decision-sweep-weekly`);
 }
 
 export function refresh(cwd, { fs, path, log }) {
@@ -683,7 +780,8 @@ export function refresh(cwd, { fs, path, log }) {
   fast:  task-fast
   task:  task-explore -> task-implement -> task-review | task-cancel
   bug:   bug-explore -> bug-fix -> bug-review | bug-cancel
-  other: decision-log`);
+  other: decision-log
+  sweep: decision-sweep-weekly`);
 }
 
 export function doctor(cwd, { fs, path, log }) {