principal-pi-skills

Use for any git or GitHub operation — "commit", "push", "open a PR", "new branch", "rebase", "merge", "tag a release", "who wrote this", "when did this break", "undo this", "wrong branch", "lost commits", "I leaked a secret", CI failures. Safe operator: refuses history rewrites on shared branches, scans for secrets before committing.

Use when turning a decision, feature, or multi-step task into an executable plan — "break this down", "how should I implement this", "where do I start", "what's the order of work", "scope this refactor", "plan the fix". Produces the plan and per-step specs; writes no code. Not for system-level design (architect) or diagnosing failures (debug).

Use when writing code — implement a feature or spec, fix a bug with a known cause, refactor — "fix this", "write the function", "implement the spec", "make the test pass", "code this up", "build it". Not for diagnosing an unknown failure (debug) or deciding what to build (plan).

Use for system design, significant technical choices (SQL vs NoSQL, monolith vs services, build vs buy, sync vs async), architecture review, migration planning, scaling questions, or recording an architecture decision — "how should I structure", "design a system that", "should we adopt X", "plan the migration", "review our architecture", "write an ADR". Not for code-level planning of a single change.

Use to review code before it lands — "review this", "is this ready to merge", "check this diff", "simplify this", "is this over-engineered", or after any non-trivial implementation. Covers both correctness (bugs, edge cases, error handling, test quality, security) and simplicity (dead code, needless abstraction, unneeded dependencies).

Use when diagnosing a failure — a failing or flaky test, a stack trace, a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it crashes when", "works on my machine". Not for writing new features or fixing a bug whose cause is already known (build).

Use when the user is exploring or deciding rather than executing — "should I", "what are my options", "which approach", "is this a good idea", "what could go wrong", "I'm stuck", or any decision that isn't settled yet. Covers software, product, business, and personal decisions. Not for building code, designing system architecture, or planning implementation.