From 1a878313f85781d8d9ca9ec2fc78b5dd28b1a6f6 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 17 Jan 2026 12:13:35 -0500 Subject: [PATCH] docs: Add Sprint 9 lessons learned Captured two lessons from Sprint 9: 1. Gitea Labels API requires org context - workaround for user repos 2. Always read CLAUDE.md before asking questions about sprint context Co-Authored-By: Claude Opus 4.5 --- docs/project-lessons-learned/INDEX.md | 2 ++ .../sprint-9-gitea-labels-user-repos.md | 29 ++++++++++++++++++ .../sprint-9-read-claude-md-first.md | 30 +++++++++++++++++++ 3 files changed, 61 insertions(+) create mode 100644 docs/project-lessons-learned/sprint-9-gitea-labels-user-repos.md create mode 100644 docs/project-lessons-learned/sprint-9-read-claude-md-first.md diff --git a/docs/project-lessons-learned/INDEX.md b/docs/project-lessons-learned/INDEX.md index 9c9f479..4045308 100644 --- a/docs/project-lessons-learned/INDEX.md +++ b/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 | diff --git a/docs/project-lessons-learned/sprint-9-gitea-labels-user-repos.md b/docs/project-lessons-learned/sprint-9-gitea-labels-user-repos.md new file mode 100644 index 0000000..a2be341 --- /dev/null +++ b/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 diff --git a/docs/project-lessons-learned/sprint-9-read-claude-md-first.md b/docs/project-lessons-learned/sprint-9-read-claude-md-first.md new file mode 100644 index 0000000..c6f8124 --- /dev/null +++ b/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