assess

> STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT. # Assess Step back and critically reassess project state. Provides interactive guidance (human-in-the-loop) and programmatic analysis (automated pipelines). Specialized for doc pruning and doc-code alignment. ## CLI Usage ```bash # Structured JSON assessment for pipelines .pi/skills/assess/assess.py run . --output assessment.json # Generate all figures from assessment create-figure from-assess --input assessment.json --output-dir ./figures/ ``` ## Assessment Flow ### 1. Scope the Assessment **Clear scope** ("assess the auth module") → proceed directly. **Open scope** ("step back") → ask: concerns? code quality vs docs? known issues to skip? **Doc pruning** ("prune documentation") → ask: deprecated features? missing docs? alignment? ### 2. Find Project Root & Detect Ecosystem Detect via marker files (pyproject.toml, package.json, Cargo.toml, go.mod). Read ecosystem-specific metadata, then universal docs (README.md, CONTEXT.md, AGENTS.md). ### 3. Load Skill Manifest (Route-Gated) Load `.pi/skills-manifest.json` for assessments that could lead to "we should build X" recommendations. Skip for status checks and doc-only reviews. ```bash cat .pi/skills-manifest.json | python3 -c " import json, sys data = json.load(sys.stdin) print(f'Skills: {data[\"skill_count\"]} (generated: {data[\"generated\"]})') " ``` Warn if manifest >7 days stale. Fallback: `ls .pi/skills/ | wc -l`. ### 4. Quick Scan → Check In → Deep Dive 1. Read project metadata, README, glob for structure 2. Note 2-3 initial observations, check in with user 3. Deep dive based on user guidance — for each finding: blocking? known? fix complexity? ### 5. Collaborative Report Present findings and ask which to fix. Offer `/create-figure` for visualization. ## Assessment Categories ### 1. Doc-Code Alignment - README claims vs implementation - Cross-reference validation (internal links, code examples) - Placeholder markers and stale information - Deprecation: docs for removed features ### 2. Aspirational vs Implemented - Stubs (`pass`, `raise NotImplementedError`), placeholder notes - Features in code structure but no logic, unused dependencies ### 3. Brittle Code - Hardcoded values, missing error handling, fragile regex/parsing ### 4. Non-Working Code - Dead code paths, silent exception swallowing, broken integrations ### 5. Over-Engineered Code - Abstractions with single implementation, config for hypothetical flexibility ### 6. Test Coverage (Non-Negotiable) Check each feature/module for test files, passing tests, edge cases. Flag `pytest.mark.skip` without reason, "0 tests collected", tests that don't assert. **Task file audit:** Verify each task has Definition of Done with specific test/assertion. Block execution if implementation tasks lack Definition of Done. ### 7. Working Well Acknowledge solid code to calibrate the assessment. ## Output Format ```markdown # Assessment: <project-name> ## Summary <2-3 sentences: overall health, key findings> ## Findings ### Doc-Code Alignment | Claim | Reality | Action? | ### Issues Found 1. **file.py:123** - [Issue] — Severity: H/M/L — Suggested fix: [brief] ### Test Coverage | Feature | Test Status | Action Needed | ### Working Well - [Solid code to acknowledge] ## Recommended Next Steps 1-4 prioritized actions. Ask which to start. ``` ## Policies - **Read-only by default** — never write files without explicit consent - **Print first, write with consent** — show proposed content, then offer to write - **Collaborate** — assessment is dialogue, not monologue - **Ask before running** — get permission before tests, builds, paid services - **Escalate wisely** — suggest `/review-code` for complex/critical issues - **Be specific** — file paths and line numbers - **Be actionable** — each finding suggests next steps - **Test coverage is non-negotiable** — flag missing tests as blockers ## External Research Available when needed (ask before paid services): - `/context7` — library docs (free) - `/brave-search` — general web (free) - `/perplexity` — deep research (paid) ## Common Mistakes ```bash # WRONG: Treat all assessment findings as blocking issues # → Agent auto-adds docstrings to 12 private helpers. Unnecessary bloat. # RIGHT: Review findings with user. Escalate complex issues to /review-code. # WRONG: Skip /assess after major changes # → README examples use old function signature. Users hit errors. # RIGHT: Run assess --focus "doc-code-alignment" after editing core APIs # WRONG: Run /assess and act on stale results # → Assessment was from 3 days ago. Codebase changed since. # RIGHT: Always re-run assess; never cache results across sessions ```