marco-souza

Capture and organize learnings from coding experiences, debugging sessions, and problem-solving. Use when: the user wants to save a learning, document a discovery, record a pattern, or create a reference for future work. Do NOT use when: creating project documentation (use docs), writing PRDs (use create-prd), or when the user wants to read existing learnings without creating new ones.

Review your own local code changes before pushing or creating a PR. Use when: the user wants to self-review staged or unstaged changes, check code quality before committing, or get feedback on work-in-progress. Covers readability, patterns, error handling, performance, and security. Do NOT use when: reviewing an existing pull request (use pr-review), reviewing code you didn't write, or when changes are already pushed to remote.

Systematically debug issues using a structured REPRO → GATHER → HYPOTHESIZE → TEST → FIX → VERIFY workflow. Use when diagnosing bugs, investigating failures, tracing errors, or troubleshooting unexpected behavior in code. Do NOT use when the issue is already identified and a fix is obvious, for code exploration without a specific problem, or for proactive code review.

Write and maintain project documentation including READMEs, API docs, ADRs, CHANGELOGs, and inline code comments. Use when: the user asks to write documentation, update a README, create an API reference, draft an ADR, add a CHANGELOG entry, or improve inline comments. Do NOT use when: the user wants to format markdown (use markdown-format), review code (use pr-review), or create a PRD (use create-prd).

Research and explore codebases to build context before making changes. Use when starting work on an unfamiliar project, investigating a bug, planning a feature, or when you need to understand how something works.

Solve complex problems by spawning multiple specialized expert agents that analyze from different angles, then synthesize their insights. Use for architecture decisions, code reviews, complex debugging, or when you need comprehensive analysis.

Manage structured communication files (PLAN.md, TODO.md, SPEC.md, etc.) to coordinate work across agents and sessions. Use when starting complex tasks, delegating to subagents, or maintaining project state.

Perform safe refactoring operations while preserving behavior and maintaining code integrity. Use when: renaming identifiers, extracting functions/modules, inlining code, moving files, or restructuring code without changing functionality. Do NOT use when: adding new features, fixing bugs (use standard editing), or making breaking API changes.

Forces the laziest solution that actually works, simplest, shortest, most minimal. Channels a senior dev who has seen everything: question whether the task needs to exist at all (YAGNI), reach for the standard library before custom code, native platform features before dependencies, one line before fifty. Supports intensity levels: lite, full (default), ultra. Use on ANY coding task: writing, adding, refactoring, fixing, reviewing, or designing code, and choosing libraries or dependencies. Also use whenever the user says "ponytail", "be lazy", "lazy mode", "simplest solution", "minimal solution", "yagni", "do less", or "shortest path", or complains about over-engineering, bloat, boilerplate, or unnecessary dependencies. Do NOT use for non-coding requests (general knowledge, prose, translation, summaries, recipes).

Read a tasks.json file, resolve dependencies, and implement each task in the correct order using the task-pipeline CLI. Use when a tasks.json exists and needs execution. Do NOT use when there is no tasks.json (use implement instead).

Convert a Product Requirements Document (PRD) into a structured tasks.json file with tasks, dependencies, priorities, and estimated effort. Use when a PRD exists and the user wants to break it down into implementable tasks. Do NOT use when there is no PRD or when the user wants to skip planning.

Structured brainstorming session using proven ideation techniques. Generate creative ideas, explore alternatives, and document your brainstorming session. Use when exploring new features, solving problems creatively, or needing multiple solution approaches before deciding.

When requirements are ambiguous, incomplete, or the agent is not 100% sure about what to implement — stop and ask clarifying questions before writing code or making changes.

A relentless one-question-at-a-time interview that stress-tests a plan or design while writing the shared vocabulary and hard decisions down as it goes. Produces a PRD.md at the end. Use when starting a new feature or project and you need deep requirements understanding before implementation.

Directly implement a feature or fix without tasks.json orchestration. Use when: the task is simple (single file, config change, straightforward feature), or when there is no tasks.json and the user wants to start coding immediately. Do NOT use when: there is a tasks.json (use implement-tasks instead), or when requirements are unclear (use grill-with-docs first).

Deep research skill for exploring codebases, searching the web, and understanding technical context. Uses Feynman Technique to ensure comprehension before proceeding. Use when you need to understand existing code, find documentation, research best practices, or gather context before implementing.

Manage structured communication files (PLAN.md, TODO.md, SPEC.md, etc.) to coordinate work across agents and sessions. Use when starting complex tasks, delegating to subagents, or maintaining project state.

Capture key decisions, pivots, and constraints discovered during work sessions. Use after architectural changes, before starting new PRDs when context has evolved, or when the user says "document this decision" or "remember this".

Interview the human-in-the-loop to clarify ambiguous requests before taking action. Use when the user's request is vague, missing key details, or has multiple valid interpretations. Do NOT use when the request is clear and unambiguous, or when the clarification can be resolved by reading code, docs, or a quick web search.

Read a tasks.json file, resolve the dependency graph, generate self-contained prompt files per task, and delegate every task to isolated tmux subagents. This skill NEVER implements code — it is a pure orchestrator. All work is done by pi subagents running in background tmux sessions.

Solve complex problems by spawning multiple specialized expert agents that analyze from different angles, then synthesize their insights. Use for architecture decisions, code reviews, complex debugging, or when you need comprehensive analysis.

Simulate Big Tech technical interviews for software engineers. Practice Coding (LeetCode-style), System Design, and Behavioral questions with feedback and coaching. Use when you want to practice for Big Tech interviews (Google, Meta, Amazon, Airbnb, etc.) or sharpen your interview skills. Do NOT use when you want live coding execution (this is for practice/feedback only) or when you need real company-specific questions (skill is company-agnostic).

Convert a Product Requirements Document (PRD) into a structured tasks.json file with tasks, dependencies, priorities, and estimated effort. Use when a PRD exists and the user wants to break it down into implementable tasks, or says "turn this into tasks," "create issues from the PRD," or "what are the next steps?" Do NOT use when there is no PRD or when the user wants to skip planning and start coding immediately.