docs: note planning is not a status (agent-facing)

.learnings/LEARNINGS.md

@@ -0,0 +1,39 @@
+# Learnings
+
+## [LRN-20260204-001] correction
+
+**Logged**: 2026-02-04T06:31:30Z
+**Priority**: high
+**Status**: pending
+**Area**: docs
+
+### Summary
+
+GitHub issues should not be posted as long walls of text; use scannable formatting.
+
+### Details
+
+User feedback: the issue body was "not well formatted" and read like a wall of text.
+
+The correct pattern for VK issues:
+
+- Short summary at top
+- Clear sections with headings
+- Bullets over paragraphs
+- Explicit Scope / Out of scope
+- Acceptance Criteria as checkboxes
+- Keep key decisions as short callouts
+
+### Suggested Action
+
+- When creating GitHub issues, default to a scannable template:
+  - Summary → Why → Current truth → Scope → Out of scope → Acceptance Criteria
+- If user requests "well formatted", keep total body length tight and avoid dense prose.
+
+### Metadata
+
+- Source: user_feedback
+- Related Files: (N/A)
+- Tags: github-issues, formatting, docs
+
+---

docs/TROUBLESHOOTING.md

@@ -21,6 +21,19 @@ Common issues and solutions for Veritas Kanban. Can't find your issue? [Open a D
 
 ## Dev Reliability (ports, hangs, and restarts)
 
+### Agent note: planning is NOT a status
+
+`planning` was removed entirely as a `TaskStatus` (process/UI heavy and overkill for an agent-first Kanban).
+
+Valid statuses are:
+
+- `todo`
+- `in-progress`
+- `blocked`
+- `done`
+
+If you need “planning”, put it in the task body/checklist or treat it as agent-internal planning — not a board column.
+
 ### Quick fix: clean restart
 
 If the UI is acting hung or the API is returning unexpected 404s, run: