diff --git a/.learnings/LEARNINGS.md b/.learnings/LEARNINGS.md
new file mode 100644
index 00000000..cd71f23d
--- /dev/null
+++ b/.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
+
+---
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 38b97883..31888fa8 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/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: