Skip to content

oliverv/caro / .agents/skills/oma-pm

oma-pm

Verified

Turn product requirements into scoped tasks with dependencies and acceptance criteria. Use for implementation planning and prioritization.

resources/error-playbook.md

View on GitHub
# PM Agent - Error Recovery Playbook

When you encounter a failure during planning, follow these recovery steps.

---

## Requirements Ambiguous

**Symptoms**: User request is vague ("Make me a good app", "Make it better")

1. Break down what you DO understand
2. List specific assumptions you're making
3. Create plan based on reasonable assumptions
4. Mark assumptions clearly: `Assumption: [description]`
5. **NEVER do this**: Create tasks whose ambiguity is left unstated. If you cannot even state a reasonable assumption for a task, stop and ask instead of planning it (agents will lose direction)

---

## Existing Codebase Unknown

**Symptoms**: Planning for an existing project but don't know the architecture

1. Use the configured provider to inspect source structure, following `../../_shared/core/code-intelligence.md`
2. Look for framework indicators: `package.json`, `pyproject.toml`, `pubspec.yaml`
3. Check for existing patterns: search for `@app.get|@app.post` (FastAPI) with the configured provider or native tools
4. If unavailable, inspect via native search and scoped reads; record any remaining architecture assumptions in the plan

---

## Task Decomposition Too Granular or Too Coarse

**Self-check**:
- Each task should take 1 agent, 10-20 turns
- If a task needs < 5 turns: merge with a related task
- If a task needs > 30 turns: split into sub-tasks
- If unsure: err on the side of fewer, larger tasks

---

## Dependency Deadlock

**Symptoms**: Task A depends on B, B depends on A (circular)

1. Identify the cycle
2. Break it by defining an API contract or shared interface first
3. Create a tier-1 task: "Define API contracts" (no dependencies), and shift the formerly-circular tasks to tier 2+
4. Both tasks then depend on the contract, not on each other

---

## Tech Stack Decision Unclear

**Symptoms**: Multiple valid options, no clear winner

1. Check existing codebase first; consistency wins over "better" tech
2. If greenfield: use the project's default stack (see SKILL.md tech-stack references)
3. Default choices: refer to each domain skill's `resources/tech-stack.md` for current versions
   - Frontend: `oma-frontend/resources/tech-stack.md`
   - Backend: `oma-backend/variants/{node,python,rust}/tech-stack.md`
   - Mobile: `oma-mobile/resources/tech-stack.md`
4. Note decision rationale in plan: `tech_decision: { choice: "X", reason: "Y" }`

---

## Workflow State / Quota Issues

Same as backend-agent playbook: see the "Rate Limit / Quota Error (LLM runtime)" and "Workflow State Unavailable" sections in `../../oma-backend/resources/error-playbook.md`.

---

## General Principles

- **Plans are not code**: They don't need to be perfect. Agents can adjust during execution
- **Blocked**: If no progress after 5 turns, save current state, `Status: blocked`
- **No code writing**: PM only plans; delegate implementation to other agents
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall