Assess

---
name: assess
description: >
  Step back and critically reassess project state. Use when asked to "assess",
  "step back", "fresh eyes", "check alignment", "sanity check", "health check",
  or "evaluate what's working". Offer to run after major changes (don't auto-run).
allowed-tools: Bash, Read, Glob, Grep
triggers:
  - assess the project
  - assess this
  - assess this directory
  - assess this folder
  - reassess this
  - reassess the project
  - re-evaluate the project
  - step back and analyze
  - step back
  - take a step back
  - fresh eyes
  - big picture check
  - check alignment
  - does the code match the docs
  - what's working and what isn't
  - evaluate code quality
  - reality check
  - sanity check
  - health check
  - project health check
  - quick audit
  - project audit
  - gap analysis
  - status check
  - project status
  - take stock
metadata:
  short-description: Step back and critically reassess project state
---

# Assess Skill

Step back and critically reassess the project state. This skill guides the agent through systematic, **collaborative** evaluation to catch drift between intent and reality.

## Key Principle: Collaborative Assessment

Assessment is a dialogue, not a report. Ask clarifying questions to:
- Understand what the user considers most important
- Clarify intent when documentation is ambiguous
- Prioritize findings based on user's goals
- Confirm assumptions before making recommendations

## Assessment Flow

### Step 1: Scope the Assessment

**If scope is clear** (e.g., "assess the auth module"), skip questions and proceed.

**If scope is open** (e.g., "step back and assess this"), ask:
- "What areas are you most concerned about?"
- "Should I focus on code quality, doc accuracy, or both?"
- "Any known issues I should acknowledge but not re-report?"

### Step 2: Find Project Root & Detect Ecosystem

Locate the project root and detect the ecosystem before reading metadata.

**Detect ecosystem first** by looking for these marker files:

| File | Ecosystem |
|------|-----------|
| `pyproject.toml`, `setup.py`, `requirements.txt` | Python |
| `package.json`, `package-lock.json`, `yarn.lock` | Node.js/JavaScript |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| `pom.xml`, `build.gradle` | Java |
| `Gemfile` | Ruby |
| `composer.json` | PHP |

**Then read ecosystem-specific metadata:**
- Python: `pyproject.toml` for dependencies, scripts, project info
- Node: `package.json` for scripts, dependencies
- Rust: `Cargo.toml` for crate info
- etc.

**Universal project docs (all ecosystems):**
```
README.md         # Project overview (check project root)
CONTEXT.md        # Agent-focused current status
AGENTS.md         # Agent skill discovery
docs/             # Documentation directory
```

**Fallback discovery** if no obvious metadata:
- Scan for `*.md` files in root
- Look for `src/` or `lib/` structure
- Check for test directories (`tests/`, `test/`, `spec/`)
- Find entry points by extension (`.py`, `.js`, `.rs`, `.go`)

### Step 3: Quick Scan & Initial Findings

Do a fast pass:
1. Read project metadata (pyproject.toml, package.json, etc.)
2. Read README.md for stated goals and features
3. Glob for structure understanding
4. Note 2-3 initial observations

Then check in (unless scope was already clear):
- "I see X, Y, Z - should I dig deeper on any of these?"
- "The docs claim [feature] - is this a priority to verify?"

### Step 4: Deep Dive

Based on user guidance, investigate thoroughly. For each finding, consider:
- Is this blocking or just technical debt?
- Does the user already know about this?
- What's the fix complexity?

### Step 5: Collaborative Report

Present findings and ask:
- "Which of these would you like me to fix now?"
- "Should I update the docs to reflect reality?"
- "Are any of these 'known issues' I should deprioritize?"

## Assessment Categories

### 1. Doc-Code Alignment
Compare what's documented vs what's implemented:
- **README claims** - Do advertised features actually exist?
- **CONTEXT.md** - Does "current status" reflect reality?
- **pyproject.toml scripts** - Do declared entry points work?
- **Config options** - Do all documented settings have effects?
- **Examples** - Do code samples in docs actually run?

**Ask:** "I found X documented but not implemented - should I implement it or update docs?"

### 2. Aspirational vs Implemented
Find gaps between intent and reality:
- Stub implementations (`pass`, `raise NotImplementedError`)
- TODO/FIXME blocking core functionality
- Features in code structure but no actual logic
- Dependencies declared but not used

**Ask:** "Is [aspirational feature] still on the roadmap, or should I remove it?"

### 3. Brittle Code
Find fragile patterns:
- Hardcoded values (URLs, paths, magic numbers)
- Missing error handling in I/O paths
- Regex/parsing that breaks on edge cases
- Version pins that may be stale

**Ask:** "I see hardcoded [value] - is this intentional for now or should I externalize it?"

### 4. Non-Working Code
Find features that exist but fail:
- Dead code paths (unreachable branches)
- Silent exception swallowing (`except: pass`)
- Integration points returning wrong data
- Import errors or missing dependencies

**Ask:** "This [feature] appears broken - is it actively used or can we remove it?"

### 5. Over-Engineered Code
Find unnecessary complexity:
- Abstractions with single implementation
- Config for hypothetical flexibility

**Ask:** "Is [abstraction] expected to grow, or can we simplify?"

### 6. Test Coverage (Non-Negotiable)
Assess whether features have corresponding tests:

**Check for each feature/module:**
- Does a test file exist? (`test_<feature>.py`, `<feature>.test.ts`)
- Do tests actually test the feature? (not just exist)
- Do tests run successfully? (exit code 0, not skipped)
- Are edge cases covered?

**Test Coverage Table:**
| Feature | Test File | Tests Run? | Pass? | Coverage |
|---------|-----------|------------|-------|----------|
| Auth login | test_auth.py | Yes | ✓ | 3 cases |
| Image extract | MISSING | - | - | NEEDS TEST |

**For missing tests, ask:**
- "Feature X has no tests. Should I create a test for it now?"
- "What behavior should the test verify?"

**For skipped tests, investigate:**
- Why is it skipped? Infrastructure issue or bug?
- "Test Y is being skipped. Should we fix the infrastructure or the test?"

**Red flags:**
- `pytest.mark.skip` without clear reason
- Exit code 3 (skip) on critical paths
- "0 tests collected" for a module
- Tests that pass but don't assert anything meaningful

### 6a. Task File Definition of Done Audit

When assessing a project with task files (0N_TASKS.md), verify each task has proper test definitions:

**Check each task for:**
- Does it have a `Definition of Done` field?
- Does the Definition specify a test file/function?
- Does the specified test actually exist?
- Is the assertion clear and verifiable?

**Task Definition of Done Audit:**
| Task | Definition of Done | Test Exists? | Assertion Clear? |
|------|-------------------|--------------|------------------|
| Task 1: Add VLM fallback | `test_image.py::test_vlm_fallback` | ✓ | ✓ |
| Task 2: Fix auth bug | MISSING | - | - |
| Task 3: Research APIs | N/A (explore) | - | - |

**For tasks missing Definition of Done:**
- "Task X has no Definition of Done. What test should prove it's complete?"
- "How will we know Task X is working correctly?"

**Block execution if:**
- Implementation tasks lack Definition of Done
- Specified tests don't exist
- Assertions are vague ("it should work")

### 7. Working Well
Acknowledge solid code - helps calibrate the assessment.

## Example Dialogue

**User:** "Step back and assess this project"

**Agent:** "I'll assess the project. A few quick questions first:
1. Are there specific areas you're concerned about?
2. Should I focus on code quality, doc accuracy, or both?
3. Any known issues I should acknowledge but not re-report?"

**User:** "Focus on whether the skills actually work as documented"

**Agent:** "I'll check the documented skills. Should I run any tests or commands to verify they work, or just review the code?"

**User:** "Yes, run the sanity tests"

**Agent:** *reads pyproject.toml, README.md, runs sanity tests*

"I've checked the documented skills. Here's what I found:

**Working as documented:**
- memory skill - recall/learn commands work
- scillm skill - batch completions working

**Drift found:**
- arxiv skill claims 'citation export' - I don't see this implemented
- youtube-transcripts example in SKILL.md uses old API format

Should I:
1. Fix the arxiv implementation to add citation export?
2. Update the docs to remove the claim?
3. Fix the youtube-transcripts example?

Which would you prefer I tackle first?"

## Output Format (When Presenting Findings)

```markdown
# Assessment: <project-name>

## Summary
<2-3 sentences: overall health, key findings>

## Scope
- **Covered:** [what was assessed]
- **Not covered:** [what was skipped or out of scope]

## Questions for You
- [Clarifying question about intent/priority]
- [Question about known issues]

## Findings

### Doc-Code Alignment
| Claim | Reality | Action? |
|-------|---------|---------|
| "Redis caching" | Not implemented | Remove claim / Implement? |

### Issues Found
1. **file.py:123** - [Issue description]
   - Severity: High/Medium/Low
   - Suggested fix: [brief]

### Working Well
- [Solid code to acknowledge]

## Test Coverage Gap
| Feature | Test Status | Action Needed |
|---------|-------------|---------------|
| [feature] | Missing | Create test |
| [feature] | Skipped | Fix infrastructure |
| [feature] | Passing | ✓ |

## Recommended Next Steps
1. [Test creation for untested features - PRIORITY]
2. [Immediate fix]
3. [Doc update]

Which should I start with? Note: Missing tests should typically be addressed first.
```

## When to Use

**On Request:**
- "Step back and assess this"
- "Sanity check the project"
- "Fresh eyes review"
- "Quick audit"
- "Health check"
- "Gap analysis"
- "Assess this directory/folder"
- "Big picture check"
- "Project status"
- "/assess"

**Proactively (always ask first, never auto-run):**
- "I've made significant changes - want me to do a quick assessment?"
- "Before I update the docs, should I verify the current state?"

## File Writing Policy: Read-Only by Default

**Core principle: Assessment is read-only. Never write files without explicit user consent.**

This prevents:
- Unexpected file changes
- Dirty git status
- Permission issues
- "Agent edited my repo" distrust

### The Print-First Pattern

When suggesting documentation, **show the content first, then offer to write**:

```
Agent: "I notice there's no README.md. Here's what I'd suggest:

---
# ProjectName

One-liner description based on pyproject.toml...

## Install
pip install ...

## Quick Start
...
---

Should I write this to README.md, or would you like to modify it first?"
```

This gives the user full control:
1. See exactly what will be written
2. Request changes before committing
3. Copy/paste themselves if preferred
4. Decline without friction

### Common Missing Docs

- `README.md` - Project overview, quick start
- `CONTEXT.md` - Current status for agents
- `CONTRIBUTING.md` - How to contribute
- `CHANGELOG.md` - Version history
- Inline docstrings for public APIs
- `--help` text for CLIs

### For Incomplete Docs

```
Agent: "The README mentions 'API endpoints' but doesn't list them.
Options:
1. I'll show you the endpoint docs to add (you approve before write)
2. Remove the mention until it's ready
3. Mark it as 'coming soon'

Which approach?"
```

**Key principle:** Print first, write only with explicit consent.

## External Research (When Needed)

Sometimes assessment requires external context. Ask before using paid services.

**Available research skills:**
| Skill | Use For | Cost |
|-------|---------|------|
| `/context7` | Library/framework documentation | Free |
| `/brave-search` | General web search, deprecation notices | Free |
| `/perplexity` | Deep research, complex questions | Paid |

**When to suggest research:**
- Verifying if a dependency is deprecated or has security issues
- Checking correct API usage for unfamiliar libraries
- Researching best practices for patterns you're unsure about
- Finding changelogs for version upgrades

**How to offer:**
```
Agent: "I see you're using library X v2.3. I'm not certain if this version
has known issues. Want me to check with /context7 or /brave-search?"
```

```
Agent: "The authentication pattern here looks unusual. Should I research
current best practices with /perplexity? (Note: this uses paid API)"
```

**Key principle:** Don't silently research - ask first, especially for paid services. Quick doc lookups with /context7 are usually fine.

## Escalation to Code Review

When assessment reveals significant issues, suggest `/code-review`:

**When to suggest code-review:**
- Complex refactoring needed across multiple files
- Architecture concerns that need deeper analysis
- Security-sensitive code paths
- Performance-critical sections
- When a second opinion from another AI provider would help

**How to suggest:**
"I've found [issues] that might benefit from a deeper code review. Want me to run `/code-review` with [provider] to get a structured analysis and patch suggestions?"

**Example:**
```
Agent: "The authentication module has several issues:
- Hardcoded secrets in 3 places
- Missing input validation
- No rate limiting

This is security-sensitive - would you like me to run `/code-review`
with OpenAI (high reasoning) to get a thorough security review and
suggested fixes?"
```

## Command Preferences

When running shell commands, prefer modern fast tools:

| Task | Prefer | Over | Why |
|------|--------|------|-----|
| Search content | `rg` (ripgrep) | `grep` | 10x faster, better defaults, respects .gitignore |
| Find files | `fd` | `find` | Faster, simpler syntax, respects .gitignore |
| List files | `eza` or `ls` | - | eza has better output if available |

Example patterns:
```bash
# Search for TODOs
rg "TODO|FIXME|HACK|XXX" --type py

# Find Python files modified recently
fd -e py --changed-within 7d

# Search for stub implementations
rg "raise NotImplementedError|pass$" --type py
```

## Tips

- **Collaborate** - Assessment is dialogue, not monologue
- **Ask before running** - Get permission before running tests, builds, or expensive commands
- **Skip questions if scope is clear** - Don't ask "what areas?" if user said "assess the auth module"
- **Prioritize** - Not every finding needs immediate action
- **Be specific** - File paths and line numbers
- **Be actionable** - Each finding should suggest next steps
- **Update as you go** - If you find drift, offer to fix it immediately
- **Escalate wisely** - Suggest code-review for complex/critical issues
- **State your scope** - Always clarify what was and wasn't assessed
- **Use fast tools** - Prefer rg/fd over grep/find for speed
- **Test coverage is non-negotiable** - Every implementation must have a test. Flag missing tests as blockers.
- **Skipped tests are red flags** - Investigate WHY tests skip. Infrastructure issues must be fixed, not ignored.