@phren/cli/starter/global/skills/phren-discover/SKILL.md

Knowledge layer for AI agents - CLI, MCP server, and data layer

---
name: phren-discover
description: Audit the phren memory store and report what needs attention, such as stale content, projects missing a summary, skill gaps and unhealthy task queues, with the top three things to fix.
dependencies:
  - git
  - gh
---
# phren-discover - Phren health check

> Audit your phren repo and tell you exactly what needs attention.

Scans your phren directory for missing files, stale content, skill gaps, and stuck task items. Outputs a concrete, prioritized action list.

**Works standalone.** Just needs a phren directory.

## When to run

- Weekly or monthly maintenance
- When you feel like things are getting messy
- Before starting a new project (to see what you've been neglecting)
- When the user asks "what should I work on"

## What to do

### 1. Find the phren directory

```bash
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
ls "$PHREN_DIR" 2>/dev/null
```

If it doesn't exist:
> "No phren directory found at ~/.phren. Run `phren-init` to set one up."

### 2. Scan all projects

For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):

```bash
for dir in "$PHREN_DIR"/*/; do
  PROJECT=$(basename "$dir")
  [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue

  [ -f "$dir/AGENTS.md" ]    && echo "$PROJECT: has AGENTS.md"    || echo "$PROJECT: MISSING AGENTS.md"
  [ -f "$dir/summary.md" ]   && echo "$PROJECT: has summary.md"   || echo "$PROJECT: MISSING summary.md"
  [ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
  [ -f "$dir/tasks.md" ]   && echo "$PROJECT: has tasks.md"   || echo "$PROJECT: MISSING tasks.md"
done
```

### 3. Check staleness

For projects that are in a git-tracked phren, check when files were last modified:

```bash
cd "$PHREN_DIR"
for dir in */; do
  PROJECT=$(basename "$dir")
  [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue

  if [ -f "$dir/FINDINGS.md" ]; then
    LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
    echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
  fi

  if [ -f "$dir/AGENTS.md" ]; then
    LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/AGENTS.md" 2>/dev/null || stat -c %Y "$dir/AGENTS.md" 2>/dev/null || stat -f %m "$dir/AGENTS.md" 2>/dev/null)
    echo "$PROJECT/AGENTS.md: last updated $LAST_MODIFIED"
  fi
done
```

Flag anything not updated in 30+ days as stale.

### 4. Detect skill gaps

Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
- Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
- A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
- A task item keeps getting deferred, and might need a skill to make it easier

Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.

### 5. Check task health

For each project with a tasks.md:
- Count total items, completed items, items with no recent progress
- Flag tasks where nothing has been completed recently
- Flag tasks with items older than 60 days that haven't moved

### 6. Scaffold missing summary.md files

For each project with a missing summary.md, output the template and offer to create it:

```
Project: myapp
MISSING: summary.md

Template:
```
# myapp

What:
Stack:
Status: active
Run:
Watch out:
```

Want me to fill this in for myapp?
```

If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.

### 7. Output the report

```
phren-discover

## Section 1: Missing files

Projects without core files:

| Project | AGENTS.md | summary.md | FINDINGS.md | tasks.md |
|---------|-----------|------------|--------------|------------|
| myapp   | ok        | MISSING    | MISSING      | ok         |
| api     | ok        | ok         | ok           | MISSING    |

## Section 2: Stale content

Files not updated in 30+ days:
- my-app/FINDINGS.md: last updated 45 days ago
- frontend/AGENTS.md: last updated 62 days ago

## Section 3: Skill gaps

Things you do repeatedly that could be skills:
- "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
- my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.

## Section 4: Task health

- my-app: 12 items (3 completed, 2 stale > 60 days)
- backend: 5 items (0 completed, all stale)
- frontend: 8 items (6 completed, healthy)

Stuck items:
- backend#2: "Add rate limiting" (added 90 days ago, no progress)
- my-app#7: "Improve query performance" (added 75 days ago, no progress)

## Top 3 things to work on next

1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
```

The "Top 3" section is the most important part. Make these:
- Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
- Prioritized (highest impact first)
- Actionable (someone could start right now)

## What not to do

- Don't flag missing files in projects that are archived or inactive
- Don't recommend creating files just for completeness; only flag what would actually help
- Don't be vague in the Top 3. Every item should be a clear next action.
- Don't pad the report with things that are fine. Focus on what needs attention.

## Related skills

- `phren-init`: scaffold missing files for a project
- `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
- `phren-consolidate`: synthesize cross-project patterns
- `/tasks`: work on stuck task items