@ai-is-gonna/get-tasks-done 0.2.0

package/get-tasks-done/workflows/extract-learnings.md

@@ -0,0 +1,242 @@
+<purpose>
+Extract decisions, lessons learned, patterns discovered, and surprises encountered from completed phase artifacts into a structured LEARNINGS.md file. Captures institutional knowledge that would otherwise be lost between phases.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<objective>
+Analyze completed phase artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md, STATE.md) and extract structured learnings into 4 categories: decisions, lessons, patterns, and surprises. Each extracted item includes source attribution. The output is a LEARNINGS.md file with YAML frontmatter containing metadata about the extraction.
+</objective>
+
+<process>
+
+<step name="initialize">
+Parse arguments and load project state:
+
+```bash
+INIT=$(gtd-sdk query init.phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`.
+
+If phase not found, exit with error: "Phase {PHASE_ARG} not found."
+</step>
+
+<step name="collect_artifacts">
+Read the phase artifacts. PLAN.md and SUMMARY.md are required; VERIFICATION.md, UAT.md, and STATE.md are optional.
+
+**Required artifacts:**
+- `${PHASE_DIR}/*-PLAN.md` — all plan files for the phase
+- `${PHASE_DIR}/*-SUMMARY.md` — all summary files for the phase
+
+If PLAN.md or SUMMARY.md files are not found or missing, exit with error: "Required artifacts missing. PLAN.md and SUMMARY.md are required for learning extraction."
+
+**Optional artifacts (read if available, skip if not found):**
+- `${PHASE_DIR}/*-VERIFICATION.md` — verification results
+- `${PHASE_DIR}/*-UAT.md` — user acceptance test results
+- `.planning/STATE.md` — project state with decisions and blockers
+
+Track which optional artifacts are missing for the `missing_artifacts` frontmatter field.
+</step>
+
+<step name="extract-learnings">
+Analyze all collected artifacts and extract learnings into 4 categories:
+
+### 1. Decisions
+Technical and architectural decisions made during the phase. Look for:
+- Explicit decisions documented in PLAN.md or SUMMARY.md
+- Technology choices and their rationale
+- Trade-offs that were evaluated
+- Design decisions recorded in STATE.md
+
+Each decision entry must include:
+- **What** was decided
+- **Why** it was decided (rationale)
+- **Source:** attribution to the artifact where the decision was found (e.g., "Source: 03-01-PLAN.md")
+
+### 2. Lessons
+Things learned during execution that were not known beforehand. Look for:
+- Unexpected complexity in SUMMARY.md
+- Issues discovered during verification in VERIFICATION.md
+- Failed approaches documented in SUMMARY.md
+- UAT feedback that revealed gaps
+
+Each lesson entry must include:
+- **What** was learned
+- **Context** for the lesson
+- **Source:** attribution to the originating artifact
+
+### 3. Patterns
+Reusable patterns, approaches, or techniques discovered. Look for:
+- Successful implementation patterns in SUMMARY.md
+- Testing patterns from VERIFICATION.md or UAT.md
+- Workflow patterns that worked well
+- Code organization patterns from PLAN.md
+
+Each pattern entry must include:
+- **Pattern** name/description
+- **When to use** it
+- **Source:** attribution to the originating artifact
+
+### 4. Surprises
+Unexpected findings, behaviors, or outcomes. Look for:
+- Things that took longer or shorter than estimated
+- Unexpected dependencies or interactions
+- Edge cases not anticipated in planning
+- Performance or behavior that differed from expectations
+
+Each surprise entry must include:
+- **What** was surprising
+- **Impact** of the surprise
+- **Source:** attribution to the originating artifact
+</step>
+
+<step name="capture_thought_integration">
+**What this step is:** `capture_thought` is an **optional convention**, not a bundled GTD tool. GTD does not ship one and does not require one. The step is a hook for users who run a memory / knowledge-base MCP server (for example ExoCortex-style servers, `claude-mem`, or `mem0`-style servers) that exposes a tool with this exact name. If any MCP server in the current session provides a `capture_thought` tool with the signature below, each extracted learning is routed through it with metadata. If no such tool is present, the step is a silent no-op — `LEARNINGS.md` is always the primary output.
+
+**Detection:** Check whether a tool named `capture_thought` is available in the current session. Do not assume any specific MCP server is connected.
+
+**If available**, call once per extracted learning:
+
+```
+capture_thought({
+  category: "decision" | "lesson" | "pattern" | "surprise",
+  phase: PHASE_NUMBER,
+  content: LEARNING_TEXT,
+  source: ARTIFACT_NAME
+})
+```
+
+**If not available** (no MCP server in the session exposes this tool, or the runtime does not support it), skip the step silently and continue. The workflow must not fail or warn — this is expected behavior for users who do not run a knowledge-base MCP.
+</step>
+
+<step name="write_learnings">
+Write the LEARNINGS.md file to the phase directory. If a previous LEARNINGS.md exists, overwrite it (replace the file entirely).
+
+Output path: `${PHASE_DIR}/${PADDED_PHASE}-LEARNINGS.md`
+
+The file must have YAML frontmatter with these fields:
+```yaml
+---
+phase: {PHASE_NUMBER}
+phase_name: "{PHASE_NAME}"
+project: "{PROJECT_NAME}"
+generated: "{ISO_DATE}"
+counts:
+  decisions: {N}
+  lessons: {N}
+  patterns: {N}
+  surprises: {N}
+missing_artifacts:
+  - "{ARTIFACT_NAME}"
+---
+```
+
+Individual items may carry an optional `graduated:` annotation (added by `graduation.md` when a cluster is promoted):
+```markdown
+**Graduated:** {target-file}:{ISO_DATE}
+```
+This annotation is appended after the item's existing fields and prevents the item from being re-surfaced in future graduation scans. Do not add this field during extraction — it is written only by the graduation workflow.
+
+The body follows this structure:
+```markdown
+# Phase {PHASE_NUMBER} Learnings: {PHASE_NAME}
+
+## Decisions
+
+### {Decision Title}
+{What was decided}
+
+**Rationale:** {Why}
+**Source:** {artifact file}
+
+---
+
+## Lessons
+
+### {Lesson Title}
+{What was learned}
+
+**Context:** {context}
+**Source:** {artifact file}
+
+---
+
+## Patterns
+
+### {Pattern Name}
+{Description}
+
+**When to use:** {applicability}
+**Source:** {artifact file}
+
+---
+
+## Surprises
+
+### {Surprise Title}
+{What was surprising}
+
+**Impact:** {impact description}
+**Source:** {artifact file}
+```
+</step>
+
+<step name="update_state">
+Update STATE.md to reflect the learning extraction:
+
+```bash
+gtd-sdk query state.update "Last Activity" "$(date +%Y-%m-%d)"
+```
+</step>
+
+<step name="report">
+```
+---------------------------------------------------------------
+
+## Learnings Extracted: Phase {X} — {Name}
+
+Decisions:  {N}
+Lessons:    {N}
+Patterns:   {N}
+Surprises:  {N}
+Total:      {N}
+
+Output: {PHASE_DIR}/{PADDED_PHASE}-LEARNINGS.md
+
+Missing artifacts: {list or "none"}
+
+Next steps:
+- Review extracted learnings for accuracy
+- /gtd:progress — see overall project state
+- /gtd:work-task-issue --phase {next} — continue to next phase
+
+---------------------------------------------------------------
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phase artifacts located and read successfully
+- [ ] All 4 categories extracted: decisions, lessons, patterns, surprises
+- [ ] Each extracted item has source attribution
+- [ ] LEARNINGS.md written with correct YAML frontmatter
+- [ ] Missing optional artifacts tracked in frontmatter
+- [ ] capture_thought integration attempted if tool available
+- [ ] STATE.md updated with extraction activity
+- [ ] User receives summary report
+</success_criteria>
+
+<critical_rules>
+- PLAN.md and SUMMARY.md are required — exit with clear error if missing
+- VERIFICATION.md, UAT.md, and STATE.md are optional — extract from them if present, skip gracefully if not found
+- Every extracted learning must have source attribution back to the originating artifact
+- Running extract-learnings twice on the same phase must overwrite (replace) the previous LEARNINGS.md, not append
+- Do not fabricate learnings — only extract what is explicitly documented in artifacts
+- If capture_thought is unavailable, the workflow must not fail — graceful degradation to file-only output
+- LEARNINGS.md frontmatter must include counts for all 4 categories and list any missing_artifacts
+</critical_rules>

package/get-tasks-done/workflows/fast.md

@@ -0,0 +1,105 @@
+<purpose>
+Execute a trivial task inline without subagent overhead. No PLAN.md, no Task spawning,
+no research, no plan checking. Just: understand → do → commit → log.
+
+For tasks like: fix a typo, update a config value, add a missing import, rename a
+variable, commit uncommitted work, add a .gitignore entry, bump a version number.
+
+Use /gtd:quick for anything that needs multi-step planning or research.
+</purpose>
+
+<process>
+
+<step name="parse_task">
+Parse `$ARGUMENTS` for the task description.
+
+If empty, ask:
+```
+What's the quick fix? (one sentence)
+```
+
+Store as `$TASK`.
+</step>
+
+<step name="scope_check">
+**Before doing anything, verify this is actually trivial.**
+
+A task is trivial if it can be completed in:
+- ≤ 3 file edits
+- ≤ 1 minute of work
+- No new dependencies or architecture changes
+- No research needed
+
+If the task seems non-trivial (multi-file refactor, new feature, needs research),
+say:
+
+```
+This looks like it needs planning. Use /gtd:quick instead:
+  /gtd:quick "{task description}"
+```
+
+And stop.
+</step>
+
+<step name="execute_inline">
+Do the work directly:
+
+1. Read the relevant file(s)
+2. Make the change(s)
+3. Verify the change works (run existing tests if applicable, or do a quick sanity check)
+
+**No PLAN.md.** Just do it.
+</step>
+
+<step name="commit">
+Commit the change atomically:
+
+```bash
+git add -A
+git commit -m "fix: {concise description of what changed}"
+```
+
+Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate.
+</step>
+
+<step name="log_to_state">
+If `.planning/STATE.md` exists, append to the "Quick Tasks Completed" table.
+If the table doesn't exist, skip this step silently.
+
+```bash
+# Check if STATE.md has quick tasks table
+if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then
+  # Append entry — workflow handles the format
+  echo "| $(date +%Y-%m-%d) | fast | $TASK | ✅ |" >> .planning/STATE.md
+fi
+```
+</step>
+
+<step name="done">
+Report completion:
+
+```
+✅ Done: {what was changed}
+   Commit: {short hash}
+   Files: {list of changed files}
+```
+
+No next-step suggestions. No workflow routing. Just done.
+</step>
+
+</process>
+
+<guardrails>
+- NEVER spawn a Task/subagent — this runs inline
+- NEVER create PLAN.md or SUMMARY.md files
+- NEVER run research or plan-checking
+- If the task takes more than 3 file edits, STOP and redirect to /gtd:quick
+- If you're unsure how to implement it, STOP and redirect to /gtd:quick
+</guardrails>
+
+<success_criteria>
+- [ ] Task completed in current context (no subagents)
+- [ ] Atomic git commit with conventional message
+- [ ] STATE.md updated if it exists
+- [ ] Total operation under 2 minutes wall time
+</success_criteria>

package/get-tasks-done/workflows/forensics.md

@@ -0,0 +1,278 @@
+# Forensics Workflow
+
+Post-mortem investigation for failed or stuck GTD workflows. Analyzes git history,
+`.planning/` artifacts, and file system state to detect anomalies and generate a
+structured diagnostic report.
+
+**Principle:** This is a read-only investigation. Do not modify project files.
+Only write the forensic report.
+
+---
+
+## Step 1: Get Problem Description
+
+```bash
+PROBLEM="$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty, ask the user:
+> "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3',
+> 'task orchestration flow failed silently', 'costs seem unusually high'."
+
+Record the problem description for the report.
+
+## Step 2: Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt to what exists.
+
+### 2a. Git History
+
+```bash
+# Recent commits (last 30)
+git log --oneline -30
+
+# Commits with timestamps for gap analysis
+git log --format="%H %ai %s" -30
+
+# Files changed in recent commits (detect repeated edits)
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+
+# Uncommitted work
+git status --short
+git diff --stat
+```
+
+Record:
+- Commit timeline (dates, messages, frequency)
+- Most-edited files (potential stuck-loop indicator)
+- Uncommitted changes (potential crash/interruption indicator)
+
+### 2b. Planning State
+
+Read these files if they exist:
+- `.planning/STATE.md` — current milestone, phase, progress, blockers, last session
+- `.planning/ROADMAP.md` — phase list with status
+- `.planning/config.json` — workflow configuration
+
+Extract:
+- Current phase and its status
+- Last recorded session stop point
+- Any blockers or flags
+
+### 2c. Phase Artifacts
+
+For each phase directory in `.planning/phases/*/`:
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, check which artifacts exist:
+- `{padded}-PLAN.md` or `{padded}-PLAN-*.md` (execution plans)
+- `{padded}-SUMMARY.md` (completion summary)
+- `{padded}-VERIFICATION.md` (quality verification)
+- `{padded}-CONTEXT.md` (design decisions)
+- `{padded}-RESEARCH.md` (pre-planning research)
+
+Track: which phases have complete artifact sets vs gaps.
+
+### 2d. Session Reports
+
+Read `.planning/reports/SESSION_REPORT.md` if it exists — extract last session outcomes,
+work completed, token estimates.
+
+### 2e. Git Worktree State
+
+```bash
+git worktree list
+```
+
+Check for orphaned worktrees (from crashed agents).
+
+## Step 3: Detect Anomalies
+
+Evaluate the gathered evidence against these anomaly patterns:
+
+### Stuck Loop Detection
+
+**Signal:** Same file appears in 3+ consecutive commits within a short time window.
+
+```bash
+# Look for files committed repeatedly in sequence
+git log --name-only --format="---COMMIT---" -20
+```
+
+Parse commit boundaries. If any file appears in 3+ consecutive commits, flag as:
+- **Confidence HIGH** if the commit messages are similar (e.g., "fix:", "fix:", "fix:" on same file)
+- **Confidence MEDIUM** if the file appears frequently but commit messages vary
+
+### Missing Artifact Detection
+
+**Signal:** Phase appears complete (has commits, is past in roadmap) but lacks expected artifacts.
+
+For each phase that should be complete:
+- PLAN.md missing → planning step was skipped
+- SUMMARY.md missing → phase was not properly closed
+- VERIFICATION.md missing → quality check was skipped
+
+### Partial-plan Drift Detection
+
+**Signal:** commits exist but SUMMARY.md is missing for the current or recently
+active plan.
+
+Run the same comparison as the task orchestration flow safe-resume verifier: identify the
+active plan from STATE.md/phase artifacts, search git history for that plan id,
+then compare against the expected SUMMARY.md path. If production commits exist
+but SUMMARY.md is missing, flag a high-confidence partial-plan drift anomaly.
+This usually means an executor was interrupted after implementation commits but
+before atomic close-out.
+
+### Abandoned Work Detection
+
+**Signal:** Large gap between last commit and current time, with STATE.md showing mid-execution.
+
+```bash
+# Time since last commit
+git log -1 --format="%ai"
+```
+
+If STATE.md shows an active phase but the last commit is >2 hours old and there are
+uncommitted changes, flag as potential abandonment or crash.
+
+### Crash/Interruption Detection
+
+**Signal:** Uncommitted changes + STATE.md shows mid-execution + orphaned worktrees.
+
+Combine:
+- `git status` shows modified/staged files
+- STATE.md has an active execution entry
+- `git worktree list` shows worktrees beyond the main one
+
+### Scope Drift Detection
+
+**Signal:** Recent commits touch files outside the current phase's expected scope.
+
+Read the current phase PLAN.md to determine expected file paths. Compare against
+files actually modified in recent commits. Flag any files that are clearly outside
+the phase's domain.
+
+### Test Regression Detection
+
+**Signal:** Commit messages containing "fix test", "revert", or re-commits of test files.
+
+```bash
+git log --oneline -20 | grep -iE "fix test|revert|broken|regression|fail"
+```
+
+## Step 4: Generate Report
+
+Create the forensics directory if needed:
+```bash
+mkdir -p .planning/forensics
+```
+
+Write to `.planning/forensics/report-$(date +%Y%m%d-%H%M%S).md`:
+
+```markdown
+# Forensic Report
+
+**Generated:** {ISO timestamp}
+**Problem:** {user's description}
+
+---
+
+## Evidence Summary
+
+### Git Activity
+- **Last commit:** {date} — "{message}"
+- **Commits (last 30):** {count}
+- **Time span:** {earliest} → {latest}
+- **Uncommitted changes:** {yes/no — list if yes}
+- **Active worktrees:** {count — list if >1}
+
+### Planning State
+- **Current milestone:** {version or "none"}
+- **Current phase:** {number — name — status}
+- **Last session:** {stopped_at from STATE.md}
+- **Blockers:** {any flags from STATE.md}
+
+### Artifact Completeness
+| Phase | PLAN | CONTEXT | RESEARCH | SUMMARY | VERIFICATION |
+|-------|------|---------|----------|---------|-------------|
+{for each phase: name | ✅/❌ per artifact}
+
+## Anomalies Detected
+
+### {Anomaly Type} — {Confidence: HIGH/MEDIUM/LOW}
+**Evidence:** {specific commits, files, or state data}
+**Interpretation:** {what this likely means}
+
+{repeat for each anomaly found}
+
+## Root Cause Hypothesis
+
+Based on the evidence above, the most likely explanation is:
+
+{1-3 sentence hypothesis grounded in the anomalies}
+
+## Recommended Actions
+
+1. {Specific, actionable remediation step}
+2. {Another step if applicable}
+3. {Recovery command if applicable — e.g., `/gtd:resume-work`, `/gtd:work-task-issue --phase N`}
+
+---
+
+*Report generated by `/gtd:forensics`. All paths redacted for portability.*
+```
+
+**Redaction rules:**
+- Replace absolute paths with relative paths (strip `$HOME` prefix)
+- Remove any API keys, tokens, or credentials found in git diff output
+- Truncate large diffs to first 50 lines
+
+## Step 5: Present Report
+
+Display the full forensic report inline.
+
+## Step 6: Offer Interactive Investigation
+
+> "Report saved to `.planning/forensics/report-{timestamp}.md`.
+>
+> I can dig deeper into any finding. Want me to:
+> - Trace a specific anomaly to its root cause?
+> - Read specific files referenced in the evidence?
+> - Check if a similar issue has been reported before?"
+
+If the user asks follow-up questions, answer from the evidence already gathered.
+Read additional files only if specifically needed.
+
+## Step 7: Offer Issue Creation
+
+If actionable anomalies were found (HIGH or MEDIUM confidence):
+
+> "Want me to create a GitHub issue for this? I'll format the findings and redact paths."
+
+If confirmed:
+```bash
+# Check if "bug" label exists before using it
+BUG_LABEL=$(gh label list --repo ai-is-gonna/get-tasks-done --search "bug" --json name -q '.[0].name' 2>/dev/null)
+LABEL_FLAG=""
+if [ -n "$BUG_LABEL" ]; then
+  LABEL_FLAG="--label bug"
+fi
+
+gh issue create \
+  --repo ai-is-gonna/get-tasks-done \
+  --title "bug: {concise description from anomaly}" \
+  $LABEL_FLAG \
+  --body "{formatted findings from report}"
+```
+
+## Step 8: Update STATE.md
+
+```bash
+gtd-sdk query state.record-session "" \
+  "Forensic investigation complete" \
+  ".planning/forensics/report-{timestamp}.md"
+```