pi-anthropic-auth: Skill for Claude Code

Improvement Discovery

Use this skill when planning the next round of structural improvements for this package. It codifies the patterns, smell categories, and analysis workflow that have proven effective across many phases of refactoring.

Analysis workflow

Follow this order — each step builds context for the next. Lead with the cause hypothesis, not the tool: fallow measures structure rather than intent, so it finds symptoms by construction and running it first frames the whole analysis around them.

1. Read the architecture document and form a cause hypothesis

Load docs/architecture.md for the current domain model, health metrics table, and dependency bag inventory. Check which bags/hotspots have already been addressed vs. remain open. Before touching any tool, write down a cause hypothesis — the first-principles structural problem the next phase should dissolve (structural fusion, a coupling/boundary flaw, a dead subsystem). The later steps corroborate, refine, or refute it. The prior phase's plan carries candidates beyond any explicit "leading candidate" line: a ⚠️ metric miss in its health-metrics table and any in-step "deferred" remark are implicit candidates, and each metric miss gets an explicit disposition in the new roadmap (re-target / accept with rationale / supersede) — never a silent drop. A cause-level finding must trace to a named target concept in the architecture doc's first-principles section (the pattern, from another Pi package: pi-permission-system's "The authority model"). When no such section exists, writing one — naming the organizing concept and recording resolved design directions — is itself a phase deliverable, not an emergent artifact: settled-in-writing directions are what make the next phase's plan cheap.

2. Sweep open issues

Run gh issue list --state open and cross-check it against the architecture doc's claims about which issues remain open — doc/tracker drift otherwise causes re-planning filed work or missing a parked candidate. An open issue that already names a cause-level finding is a pre-discovered candidate — adopt it as a phase step under its existing number rather than re-deriving it. Sweep recorded deferred tidyings too: grep -r -A 5 '#### Deferred tidyings' docs/retro/. Each is a finding a tidy-first-assessor judged real but out of scope for the change it was dispatched over — triage it like any other candidate, or say why it stays deferred. Track repeat deferrals: an issue swept as out-of-scope across multiple consecutive phases gets an explicit decision this phase — schedule it into the phase, or recommend closing it as not-planned — never a silent re-defer. Structural phases must not starve feature and bug work indefinitely.