docs/project-lessons-learned/INDEX.md

@@ -10,6 +10,8 @@ This folder contains lessons learned from sprints and development work. These le
 
 | Date | Sprint/Phase | Title | Tags |
 |------|--------------|-------|------|
+| 2026-01-17 | Sprint 9 | [Gitea Labels API Requires Org Context](./sprint-9-gitea-labels-user-repos.md) | gitea, mcp, api, labels, projman, configuration |
+| 2026-01-17 | Sprint 9 | [Always Read CLAUDE.md Before Asking Questions](./sprint-9-read-claude-md-first.md) | projman, claude-code, context, documentation, workflow |
 | 2026-01-17 | Sprint 9-10 | [Graceful Error Handling in Service Layers](./sprint-9-10-graceful-error-handling.md) | python, postgresql, error-handling, dash, graceful-degradation, arm64 |
 | 2026-01-17 | Sprint 9-10 | [Modular Callback Structure](./sprint-9-10-modular-callback-structure.md) | dash, callbacks, architecture, python, code-organization |
 | 2026-01-17 | Sprint 9-10 | [Figure Factory Pattern](./sprint-9-10-figure-factory-pattern.md) | plotly, dash, design-patterns, python, visualization |

docs/project-lessons-learned/sprint-9-gitea-labels-user-repos.md

@@ -0,0 +1,29 @@
+# Sprint 9 - Gitea Labels API Requires Org Context
+
+## Context
+Creating Gitea issues with labels via MCP tools during Sprint 9 planning for the personal-portfolio project.
+
+## Problem
+When calling `create_issue` with a `labels` parameter, received:
+```
+404 Client Error: Not Found for url: https://gitea.hotserv.cloud/api/v1/orgs/lmiranda/labels
+```
+
+The API attempted to fetch labels from an **organization** endpoint, but `lmiranda` is a **user account**, not an organization.
+
+## Solution
+Created issues without the `labels` parameter and documented intended labels in the issue body instead:
+```markdown
+**Labels:** Type/Feature, Priority/Medium, Complexity/Simple, Efforts/XS, Component/Docs, Tech/Python
+```
+
+This provides visibility into intended categorization while avoiding the API error.
+
+## Prevention
+- When working with user-owned repos (not org repos), avoid using the `labels` parameter in `create_issue`
+- Document labels in issue body as a workaround
+- Consider creating a repo-level label set for user repos (Gitea supports this)
+- Update projman plugin to handle user vs org repos differently
+
+## Tags
+gitea, mcp, api, labels, projman, configuration

docs/project-lessons-learned/sprint-9-read-claude-md-first.md

@@ -0,0 +1,30 @@
+# Sprint 9 - Always Read CLAUDE.md Before Asking Questions
+
+## Context
+Starting Sprint 9 planning session with `/projman:sprint-plan` command.
+
+## Problem
+Asked the user "what should I do?" when all the necessary context was already documented in CLAUDE.md:
+- Current sprint number and phase
+- Implementation plan location
+- Remaining phases to complete
+- Project conventions and workflows
+
+This caused user frustration: "why are you asking what to do? cant you see this yourself"
+
+## Solution
+Before asking any questions about what to do:
+1. Read `CLAUDE.md` in the project root
+2. Check "Project Status" section for current sprint/phase
+3. Follow references to implementation plans
+4. Review "Projman Plugin Workflow" section for expected behavior
+
+## Prevention
+- **ALWAYS** read CLAUDE.md at the start of any sprint-related command
+- Look for "Current Sprint" and "Phase" indicators
+- Check for implementation plan references in `docs/changes/`
+- Only ask questions if information is genuinely missing from documentation
+- The projman plugin expects autonomous behavior based on documented context
+
+## Tags
+projman, claude-code, context, documentation, workflow, sprint-planning