phren-discover

name	phren-discover
description	Audit your phren repo and tell you exactly what needs attention.
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

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/):

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

  [ -f "$dir/CLAUDE.md" ]    && echo "$PROJECT: has CLAUDE.md"    || echo "$PROJECT: MISSING CLAUDE.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:

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/CLAUDE.md" ]; then
    LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
    echo "$PROJECT/CLAUDE.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 | CLAUDE.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/CLAUDE.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