ponshu-room-lite/docs

📚 Ponshu Room Lite - Documentation Index

Last Updated: 2026-01-21
Purpose: Central navigation for all project documentation
Audience: AI collaborators (Claude, Antigravity, Gemini) + Human developers

---

🚀 Quick Start (For New AI Collaborators)

Read these first:

1. CURSOR_CHAT_MASTER_CONTEXT.md - Antigravity handoff context
2. PROJECT_TODO.md - Current tasks and priorities
3. DARK_MODE_COLOR_GUIDELINES.md - Critical: Read before any UI changes

---

📋 Task Management

Document	Purpose	When to Use
PROJECT_TODO.md	Active tasks, deferred work	Before starting any work
PROJECT_BACKLOG_MASTER.md	High-level roadmap (52 tasks)	Strategic planning
UI_UX_BACKLOG.md	UI/UX improvements (18 tasks)	Design work

---

🎨 Design & Implementation Guidelines

Document	Purpose	When to Use
DARK_MODE_COLOR_GUIDELINES.md	Critical: Dark Mode patterns	Before ANY UI changes
PHASE_2_IMPLEMENTATION_PLAN.md	Phase 2 feature specs	Implementing Phase 2 features
gamification_specification.md	Badge/Level/EXP system	Gamification work

---

🏗️ Architecture & Technical

Document	Purpose	When to Use
ARCHITECTURE_DECISION_RECORD.md	Key technical decisions	Understanding "why"
CURSOR_CHAT_MASTER_CONTEXT.md	Antigravity handoff	Understanding project history
TRANSLATION_STATUS.md	i18n status	Translation work

---

🎯 Feature-Specific Documentation

Business Mode

• BUSINESS_MODE_SPECIFICATION.md - Business features (menu creation, pricing)

Future Plans

• future_plan.md - Archived long-term ideas
• RECOMMENDATION_EXPANSION_PLAN.md - "あわせて飲みたい" expansion (Phase 3)

---

🔍 Finding Information

"Where should I...?"

Q: Fix a Dark Mode visibility issue?
→ Read DARK_MODE_COLOR_GUIDELINES.md first
→ Check PROJECT_TODO.md for deferred Dark Mode fixes

Q: Add a new feature?
→ Check PROJECT_TODO.md for current priorities
→ Review PROJECT_BACKLOG_MASTER.md for planned features
→ See if it conflicts with PHASE_2_IMPLEMENTATION_PLAN.md

Q: Fix a badge/level/gamification issue?
→ gamification_specification.md

Q: Understand past decisions?
→ ARCHITECTURE_DECISION_RECORD.md
→ CURSOR_CHAT_MASTER_CONTEXT.md

Q: Add business mode features?
→ BUSINESS_MODE_SPECIFICATION.md

Q: Find a TODO/task?
→ PROJECT_TODO.md - Active/urgent tasks
→ PROJECT_BACKLOG_MASTER.md - All 52 tasks
→ UI_UX_BACKLOG.md - UI/UX-specific

---

🚨 Critical Rules (DO NOT SKIP)

Before Modifying UI Code:

1. ✅ Read DARK_MODE_COLOR_GUIDELINES.md
2. ✅ Never use Colors.blue, Color(0xFF...) hardcoded colors
3. ✅ Never use brightness == Brightness.dark manual checks
4. ✅ Always use Theme.of(context).colorScheme.xxx

Before Adding Features:

1. ✅ Check PROJECT_TODO.md for current priorities
2. ✅ Check PROJECT_BACKLOG_MASTER.md for planned work
3. ✅ Run flutter analyze before and after changes

Before Committing:

1. ✅ Update relevant documentation
2. ✅ Run flutter analyze and fix new warnings
3. ✅ Test in both Light and Dark modes

---

📦 Document Status

Status	Meaning
✅ Complete	Up-to-date, use as reference
🔄 Needs Update	Partially outdated, use with caution
📝 In Progress	Being actively updated
🗃️ Archived	Historical reference only

Current Status

• ✅ DARK_MODE_COLOR_GUIDELINES.md
• ✅ PROJECT_TODO.md
• ✅ CURSOR_CHAT_MASTER_CONTEXT.md
• ✅ ARCHITECTURE_DECISION_RECORD.md
• ✅ gamification_specification.md
• 🔄 PROJECT_BACKLOG_MASTER.md (needs Dark Mode status update)
• 🔄 UI_UX_BACKLOG.md (needs Coach Mark status update)
• 📝 PHASE_2_IMPLEMENTATION_PLAN.md (being created)
• 🗃️ future_plan.md (archived)

---

🤝 For AI Collaborators

Communication Protocol

• Update PROJECT_TODO.md when tasks change
• Leave comments in code explaining "why", not "what"
• Follow guidelines strictly to avoid breaking existing work

Handoff Checklist

When transferring work to another AI:

• Update PROJECT_TODO.md with progress
• Document any deferred decisions
• Note any discovered issues
• Update relevant spec documents

---

📞 Contact & Maintenance

Project Owner: User (Maita)
Primary AI: Claude Sonnet 4.5 (via Cursor)
Collaborators: Antigravity, Gemini

To update this index: Edit this file when adding/removing documentation.

Last Major Update: 2026-01-21 (Dark Mode Phase 1 completion)

---

🗺️ Document Map (Visual)

docs/
├── README.md (← YOU ARE HERE)
├── PROJECT_TODO.md ⭐ START HERE
├── PROJECT_BACKLOG_MASTER.md (52 tasks)
├── UI_UX_BACKLOG.md (18 UI tasks)
│
├── Guidelines/
│   ├── DARK_MODE_COLOR_GUIDELINES.md ⭐ CRITICAL
│   └── TRANSLATION_STATUS.md
│
├── Implementation Plans/
│   ├── PHASE_2_IMPLEMENTATION_PLAN.md (Phase 2 features)
│   ├── BUSINESS_MODE_SPECIFICATION.md
│   ├── gamification_specification.md
│   └── RECOMMENDATION_EXPANSION_PLAN.md (Phase 3)
│
├── Architecture/
│   ├── ARCHITECTURE_DECISION_RECORD.md
│   ├── CURSOR_CHAT_MASTER_CONTEXT.md (Antigravity handoff)
│   └── (other arch docs)
│
└── Archive/
    └── future_plan.md (historical)