feat: memory type classification + auto-capture pitfalls on NEEDS_WORK

- flowctl memory add --type pitfall|convention|decision|general (default: general)
- flowctl memory list --type <filter> to show entries by type
- impl_review auto-captures pitfall when review returns NEEDS_WORK
- Worker Phase 6 records pitfalls from self-review fixes
- Worker Phase 10 uses typed entries (pitfall/convention/decision/general)
- Code review skill auto-captures Critical/Important findings as pitfalls
- Brainstorm step-02 reads pitfall memory to avoid known failure patterns
- Backward compatible: existing entries without type default to general

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

agents/worker.md

@@ -574,6 +574,11 @@ Also check:
 
 If you find issues, fix them and re-run `<FLOWCTL> guard` to verify.
 
+If self-review finds issues that required fixes, record as pitfall:
+```bash
+<FLOWCTL> memory add pitfall "Self-review: <what was wrong>"
+```
+
 **Rules:**
 - Only fix issues in YOUR changes — don't refactor unrelated code
 - If unsure whether something is an issue, leave it for Phase 8 (external review)
@@ -782,6 +787,13 @@ If enabled, reflect on what you discovered during implementation and save **only
   <FLOWCTL> memory add decision "What was decided and why"
   ```
 
+- **General**: Observations that don't fit the above categories
+  ```bash
+  <FLOWCTL> memory add general "Observation description"
+  ```
+
+Use the most specific type: failure patterns → `pitfall`, project conventions → `convention`, architecture choices → `decision`, everything else → `general`.
+
 **Rules:**
 - Only save if you genuinely discovered something non-obvious
 - Don't repeat what's already in the spec or README

bin/flowctl

@@ -17,7 +17,7 @@ use super::helpers::get_flow_dir;
 
 // ── Constants ──────────────────────────────────────────────────────
 
-const MEMORY_VALID_TYPES: &[&str] = &["pitfall", "convention", "decision"];
+const MEMORY_VALID_TYPES: &[&str] = &["pitfall", "convention", "decision", "general"];
 
 const VALID_SEVERITIES: &[&str] = &["critical", "high", "medium", "low"];
 
@@ -77,11 +77,11 @@ pub enum MemoryCmd {
     Init,
     /// Add atomic memory entry.
     Add {
-        /// Type: pitfall, convention, or decision.
-        #[arg(name = "type")]
-        entry_type: String,
         /// Entry content.
         content: String,
+        /// Type: pitfall, convention, decision, or general.
+        #[arg(long = "type", default_value = "general", value_parser = ["pitfall", "convention", "decision", "general"])]
+        entry_type: String,
         /// Module scope (e.g. "flowctl-core", "scheduler", "auth").
         #[arg(long)]
         module: Option<String>,
@@ -509,11 +509,11 @@ fn cmd_memory_add(
         None => {
             if json {
                 json_output(json!({
-                    "error": format!("Invalid type '{}'. Use: pitfall, convention, or decision", entry_type)
+                    "error": format!("Invalid type '{}'. Use: pitfall, convention, decision, or general", entry_type)
                 }));
             } else {
                 eprintln!(
-                    "Error: Invalid type '{}'. Use: pitfall, convention, or decision",
+                    "Error: Invalid type '{}'. Use: pitfall, convention, decision, or general",
                     entry_type
                 );
             }
@@ -684,11 +684,11 @@ fn cmd_memory_read(json: bool, entry_type: Option<&str>) {
     if entry_type.is_some() && type_filter.is_none() {
         if json {
             json_output(json!({
-                "error": format!("Invalid type '{}'. Use: pitfall, convention, or decision", entry_type.unwrap())
+                "error": format!("Invalid type '{}'. Use: pitfall, convention, decision, or general", entry_type.unwrap())
             }));
         } else {
             eprintln!(
-                "Error: Invalid type '{}'. Use: pitfall, convention, or decision",
+                "Error: Invalid type '{}'. Use: pitfall, convention, decision, or general",
                 entry_type.unwrap()
             );
         }

flowctl/crates/flowctl-cli/src/commands/memory.rs

@@ -17,6 +17,10 @@ FLOWCTL="$HOME/.flow/bin/flowctl"
 4. Read key config files, README, CLAUDE.md for project constraints
 5. Identify affected modules, dependencies, and integration points
 6. Read `.flow/project-context.md` Non-Goals and Architecture Decisions. Do NOT propose approaches that conflict with Non-Goals. Reference Architecture Decisions to avoid re-debating settled choices.
+7. Read pitfalls specifically to avoid known failure patterns:
+   ```bash
+   $FLOWCTL memory list --type pitfall --json
+   ```
 
 ## Classify Complexity
 

skills/flow-code-brainstorm/steps/step-02-context-gather.md

@@ -297,3 +297,10 @@ After completing a review:
 - [ ] Change size noted if >500 lines
 - [ ] Tests reviewed before implementation
 - [ ] No rubber-stamping — every approval reflects genuine review
+
+## Auto-Capture Pitfalls
+When verdict is NEEDS_WORK, the orchestrator should capture each Critical/Important finding as a pitfall:
+```bash
+$FLOWCTL memory add pitfall "Review: <finding summary>"
+```
+This builds project memory from review failures, preventing the same mistakes in future tasks.

skills/flow-code-code-review/SKILL.md

@@ -146,6 +146,10 @@ Detect input type to decide whether to execute or skip:
    - Acceptance Auditor (diff + spec + project-context.md)
 5. Merge findings, apply zero-findings rule
 6. Fix Critical/Important issues until SHIP (max 2 iterations)
+   When a review returns NEEDS_WORK, auto-capture the key findings as memory pitfalls:
+   ```bash
+   $FLOWCTL memory add pitfall "Review finding: <summary of what was wrong and how it was fixed>"
+   ```
 
 ### Close (close)
 1. Validate: $FLOWCTL validate --epic $EPIC_ID --json