diff --git a/docs/standards/FFG-STD-002-task-documentation.md b/docs/standards/FFG-STD-002-task-documentation.md index 6746b18..8458ba9 100644 --- a/docs/standards/FFG-STD-002-task-documentation.md +++ b/docs/standards/FFG-STD-002-task-documentation.md @@ -5,7 +5,7 @@ **Created:** February 16, 2026 **Created By:** The Chronicler (current session) **Authority:** Michael "Frostystyle" Krause + The Chronicler -**Version:** 1.0 +**Version:** 2.0 (Updated March 26, 2026) **Applies To:** All tasks in `docs/core/tasks.md` --- @@ -298,6 +298,192 @@ git commit -m "Update [task-name]: [what changed]" --- +## ⚡ DECISION CAPTURE RULE (CRITICAL) + +### The Problem: Verbal Decision → Lost Context + +**What happens:** +1. Michael makes a decision during a session (add platforms, change priority, assign to someone) +2. Chronicler remembers the decision in session context +3. Decision is NOT immediately documented in task files +4. Next Chronicler reads task files, decision is completely lost +5. Work gets marked "supposed to be done" but has no documentation + +**Real example (March 2026):** +- Decision: Add Reddit, Bluesky, Mastodon, Kick to social media platforms +- NOT documented in Task #56 +- Next Chronicler had no idea these platforms were decided +- Created documentation gap that looked like failed work + +### The Rule: Immediate Documentation + +**WHENEVER Michael makes a decision that affects a task, the Chronicler MUST:** + +**Within 5 minutes:** +1. Update the relevant task documentation (tasks.md or task directory files) +2. Commit with message: `docs: Update Task #XX - [decision]` +3. Push to Gitea before continuing other work + +**Examples of decisions requiring immediate documentation:** +- ✅ Adding items to a list (platforms, features, requirements) +- ✅ Changing task priority or status +- ✅ Assigning task to someone (Meg, Holly, team member) +- ✅ Setting deadlines or dependencies +- ✅ Deciding to defer or cancel work +- ✅ Changing scope (add/remove deliverables) +- ✅ Resource allocation decisions + +**This applies even for "small" decisions** - if it changes what's documented, document it NOW. + +### Why This Is Non-Negotiable + +**Without immediate documentation:** +- Next Chronicler has no record of the decision +- Handoffs become "he said / she said" +- Work gets duplicated or missed entirely +- Context slowly degrades across sessions + +**With immediate documentation:** +- All Chroniclers work from same source of truth +- Decisions are traceable (Git history shows when/why) +- No "supposed to be done" confusion +- Clean handoffs between sessions + +### Workflow Example + +```bash +# Michael says: "Add Reddit to the social media platform list" + +# IMMEDIATELY (before continuing conversation): +cd /home/claude/firefrost-operations-manual +vim docs/core/tasks.md +# Add Reddit to Task #56 platform list + +git add docs/core/tasks.md +git commit -m "docs: Update Task #56 - Add Reddit to platform list + +Decision made during session with Michael (2026-03-26). +Expands social media presence from 10 to 11 platforms." +git push + +# THEN continue with other work +``` + +**Time cost:** 2-3 minutes per decision +**Value:** Prevents hours of confusion and rework + +### Exception: Exploratory Discussions + +**NOT every conversation requires documentation:** + +- ❌ "What if we..." brainstorming (no decision made) +- ❌ "How would X work?" technical questions (no commitment) +- ❌ "Maybe someday..." future possibilities (not actionable) + +**Only DECISIONS require immediate documentation:** +- ✅ "Yes, add that platform" (decision made) +- ✅ "Assign this to Meg" (decision made) +- ✅ "This is now high priority" (decision made) + +**When in doubt:** Ask Michael: "Should I document this decision now?" + +--- + +## 📊 TASK STATUS PRECISION + +### The Problem: Vague Status Labels + +**Current status labels are ambiguous:** +- "READY" - Ready to start? Prerequisites ready? Ready to finish? +- "PENDING" - Pending what? Who? When? +- "BLOCKED" - Blocked by what specifically? + +This creates handoff confusion where next Chronicler doesn't know actual state. + +### New Status System + +**Use these precise status indicators:** + +**✅ COMPLETE** +- Work is done and verified +- Deliverables deployed and tested +- Documentation updated +- Include completion date + +**🔄 IN PROGRESS** +- Active work happening this session +- Clear who is working on it +- Expected completion timeframe noted + +**⏳ WAITING - [Specific Dependency]** +- Blocked by external dependency +- **MUST document WHO or WHAT we're waiting on** +- Examples: + - `⏳ WAITING - Meg creating accounts (2/11 done, slow progress)` + - `⏳ WAITING - Breezehost unblocking port 25` + - `⏳ WAITING - Holly reviewing build design` + +**📋 READY** +- All prerequisites met +- Can start immediately +- No blockers or dependencies + +**❌ BLOCKED - [Specific Blocker]** +- Cannot proceed +- **MUST document what's blocking** +- Examples: + - `❌ BLOCKED - Task #38 (security update) must complete first` + - `❌ BLOCKED - API credentials not yet created` + +**🗓️ PLANNED** +- Future work +- Not yet ready to start +- Prerequisites not met + +### Required Context for WAITING Status + +**NEVER use just "WAITING"** - always include: +1. **What/who we're waiting on** (person, service, approval) +2. **Current progress** (if applicable: "2/11 done") +3. **Velocity assessment** (fast/slow/stalled) +4. **Critical path impact** (does this block soft launch?) + +**Example - Good:** +```markdown +**Status:** ⏳ WAITING - External dependency +**Assigned:** Meg (community manager) +**Progress:** 2/11 platforms complete (Discord, Facebook done) +**Velocity:** Slow (accounts created on Meg's timeline) +**Critical Path:** Not blocking soft launch (footer shows "Coming Soon") +``` + +**Example - Bad:** +```markdown +**Status:** PENDING +``` + +### Why This Matters + +**Precise status enables:** +- ✅ Next Chronicler knows exact state without asking +- ✅ Can assess critical path impact immediately +- ✅ Knows who to follow up with +- ✅ Understands timeline expectations +- ✅ No "supposed to be done" confusion + +**Vague status creates:** +- ❌ "What does READY mean here?" +- ❌ "Who do I ask about this?" +- ❌ "Is this blocking anything?" +- ❌ Wasted time hunting for context + +### Migration Note + +Existing tasks will be updated to new status system as they're touched. +New tasks MUST use precise status from creation. + +--- + ## 📚 NAMING CONVENTIONS ### Directory Names @@ -766,6 +952,19 @@ See also: ## 📋 CHANGELOG +### Version 2.0 (2026-03-26) +**Added by:** The Verifier (Chronicler #42) +**Reason:** Documentation process breakdown (NEXT-SESSION-PRIORITY.md) + +**Major additions:** +- ⚡ Decision Capture Rule (CRITICAL) - Immediate documentation of all decisions +- 📊 Task Status Precision - New 6-status system with required context +- Eliminated "verbal decision → lost context" failure mode +- Required WHO/WHAT context for WAITING status +- Examples of good vs bad status documentation + +**Impact:** Prevents documentation gaps between Chronicler sessions + ### Version 1.0 (2026-02-16) - Initial standard created - Established directory structure