Project Refine

Project Refine

Answer the question: could this project be smaller, clearer, or better structured?

A dedicated improvement session across documentation and code (including tests). Looks at things that already work and asks whether they could be better. Never blocks work — findings are always opportunities, never failures.

---

Step 0 — Read Project Type and Configuration

Read project type (for context, not routing — project-refine is always the right skill regardless of type):

python3 ~/.claude/skills/project-init/ctx.py

Read PROJECT_TYPE from the output.

Also read Health Check Configuration from CLAUDE.md:

grep -A 10 "## Health Check Configuration" CLAUDE.md 2>/dev/null

Parse from ## Health Check Configuration:

• Default refine domains: → domains to run (default: docs, code, universal)
• Default refine tier: → tier if not specified (default: 2)
• Refine min score: → minimum bloat score to report (all | medium | high) (default: all)
• Additional doc paths: → extra paths to scan

---

Step 1 — Determine Tier

Parse flags from the invocation:

| Flag | Tier | |------|------| | --tier 1 | Structural checks only, no file reading (~2 min) | | --tier 2 | Read top candidates by churn and size (~10 min) | | --tier 3 | Deeper scan, IntelliJ MCP if available (~20 min) | | --tier 4 | Full scope, prompted for focus area (~30–45 min) |

Also parse:

• --save → write report to YYYY-MM-DD-refine-report.md after output
• --compare → show only findings not present in a previous report
• Domain names (docs, code, universal) → run only those domains

If no tier flag is given (and no Default refine tier configured), prompt:

> How thorough should this refinement session be? > > 1 — Quick — structural checks only, no file reading (~2 min) > 2 — Standard — read top candidates by churn and size (~10 min) > 3 — Full — deeper scan, IntelliJ MCP if available (~20 min) > 4 — Deep — full scope, prompted for focus area (~30–45 min) > > Enter 1–4 (default: 2):

Wait for response. If no response, use tier 2.

---

Step 2 — Focus Prompt (Tier 2+)

Before scanning code at tier 2 or above, ask:

> Would you like to focus on a specific directory or package? > > Enter a path (e.g. src/main/java/com/example/payment), or type "auto" > to use git history and file size to find candidates automatically.

Wait for response. If a path is provided, limit code scanning to that path. If Enter, proceed with automatic candidate selection.

---

Step 3 — Build Scan Candidates

Docs candidates

Build the document scan list using the same scope as project-health:

Always included:

• All .md files under doc/, docs/, documentation/ (recursive, case-insensitive)
• Root-level .md files (all of them)
• Any README.md, CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md anywhere in tree
• Additional paths from CLAUDE.md Health Check Configuration

Tier 1 (structural only — no file reading):

find . -name "*.md" -not -path "./.git/*" | xargs wc -l 2>/dev/null | sort -rn | head -20

Identify docs by line count. Flag files over ~400 lines as candidates.

Tier 2: Read the top 5 docs by line count. Tier 3+: Read all docs over 200 lines. Read everything if under 30 files total.

Code candidates

If a focus path was given, start there. Otherwise:

Tier 1 (no file reading):

# Files by size
find . -name "*.py" -o -name "*.java" -o -name "*.ts" -o -name "*.go" | grep -v ".git" | xargs wc -l 2>/dev/null | sort -rn | head -20

# Files by churn (most frequently changed)
git log --format=format: --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20

# Repeated literals
grep -r --include="*.py" --include="*.java" --include="*.ts" -h "\"[^\"]\{8,\}\"" . 2>/dev/null | sort | uniq -c | sort -rn | head -10

Tier 2: Read top 10 files by churn+size combined ranking. Tier 3: Read top 20 files. Use IntelliJ MCP semantic search if available:

• ide_find_references to check for unused code
• ide_search_text for repeated patterns

Tier 4: Read all files above size threshold plus user-specified focus area.

---

Step 4 — Run Refinement Domains

Run the configured domains (docs, code, universal). Skip domains excluded by the invocation or CLAUDE.md configuration.

docs — Documentation Structure & Readability

> Could documentation be better structured, smaller, or easier to read?

Structure & organisation

• [ ] Would a different grouping or ordering of sections improve navigation?
• [ ] Are there docs over ~400 lines with multiple distinct topics that would be clearer as separate linked files?
• [ ] Are there multiple small files covering closely related topics that would read better merged?
• [ ] Are related topics scattered across documents that should be consolidated?

Readability

• [ ] Passive voice, unexplained jargon, walls of text, or sentences over 25 words?
• [ ] Could any prose be replaced with a table or example easier to scan?
• [ ] Is the detail level appropriate for the intended audience?

Dead weight

• [ ] Sections that restate what was just said, or introductory paragraphs that add no information?
• [ ] Sections describing plans, history, or context that are no longer relevant?
• [ ] Documents or sections never read because they're hard to find or navigate to?

Consistency of structure

• [ ] Do tables of the same type use consistent column order and headers throughout?
• [ ] Do documents introduce concepts and define them paragraphs later (forward references)?

---

code — Deduplication, Abstraction & Organisation

> Could code (including tests) be deduplicated, abstracted, or better organised?

Duplication

• [ ] Same blocks of logic appearing 3+ times? (high risk: fix one, miss others)
• [ ] Similar but not identical blocks that should be parameterised and shared?
• [ ] Literal values (strings, numbers, paths) repeated in multiple places?
• [ ] Same fixture or arrangement code copy-pasted across multiple test methods?
• [ ] Test patterns repeated enough to extract into shared helpers or base classes?

Abstraction opportunities

• [ ] Repeated sequences of calls that always appear together, belonging in a helper?
• [ ] Functions over ~30 lines combining multiple distinct concerns?
• [ ] Missing abstractions that would make the code more expressive?

Organisation

• [ ] Tests for one feature spread across multiple files without clear ownership?
• [ ] Tests that would benefit from being grouped to reflect the structure of what they test?
• [ ] Test names follow a consistent pattern making it easy to see what's covered?
• [ ] Files (source or test) over size guideline that test multiple unrelated concerns?
• [ ] Shared test fixtures hiding critical preconditions?

Dead code

• [ ] Commented-out code? (remove it — git history preserves it)
• [ ] Functions, classes, or modules never called?
• [ ] Feature flags or compatibility shims for things that no longer exist?

Scattered configuration

• [ ] Configuration values or defaults defined in multiple files that should be consolidated?
• [ ] Error handling inconsistent across similar operations?

---

universal — Bloat Across All Areas

> What is oversized, over-engineered, or unnecessarily complex anywhere in the project?

• [ ] Files >50% larger than the guideline for their type? (SKILL.md: ~400 lines, test files: ~300 lines)
• [ ] Logic or document sections nested >3 levels deep that could be flattened?
• [ ] Functions with >4 parameters that could be grouped into a config object?
• [ ] Complex solutions for problems that have a simpler answer?
• [ ] More comment lines than code lines explaining obvious things?
• [ ] Dependencies larger than the value they provide?

---

Step 5 — Score and Present Findings

Rate every finding on two axes:

Size reduction potential:

• 🔴 HIGH — >30% reduction possible
• 🟡 MEDIUM — 10–30% reduction possible
• 🟢 LOW — "If someone fixes this, does it significantly change how quickly a reader understands the code or doc — or prevent them from acting on wrong information?"

> If yes → upgrade to A, regardless of how small the change is.

Common 🟢A patterns (small change, large impact):

• A capability doc says a feature is "Research phase" but it shipped — one paragraph fix, but every reader who evaluates the project is misled until it's corrected
• A hot-path method (called on every write) is 60 lines mixing 6 concerns — extracting one private method halves visual complexity permanently
• A missing class-level comment on a class with non-obvious invariants — two sentences, but saves every future contributor 10 minutes of archaeology

Detailed findings:

## project-refine — Opportunities Found

### 🔴A — High impact, significant size reduction
- scripts/validate_all.py (lines 45–89): run_validator() logic repeated
  for each tier; extract to a shared helper. Est. -40 lines. [code]

### 🟡A — High impact, medium size reduction
- OrderService.processOrder() (85 lines): mixes validation, business logic,
  and persistence; split into three methods. Est. -25 lines from save(). [code]

### 🟢A — High impact, small size reduction
- CAPABILITIES.md:313: "Current state: Research phase" — feature shipped six
  months ago; every evaluator reads this and thinks it doesn't exist. Fix: 2
  sentences. [docs]

### 🟡B — Medium impact
- update-primary-doc/SKILL.md (312 lines): Steps 4–7 cover two unrelated
  concerns; splitting would improve navigation. Est. -20 lines. [docs]

### 🟢C — Low impact, cosmetic
- java-dev/SKILL.md: "Code duplication" and "Code clarity" sections are
  adjacent and both cover style; could merge. Est. -5 lines. [docs]

### Nothing found
✅ universal

Findings are opportunities, never failures. Do NOT use CRITICAL, HIGH, MEDIUM, LOW severity language (that belongs to project-health). Use bloat scores only.

Never auto-apply changes. All findings are judgment calls. Present opportunities; the user decides what to act on.

---

Step 6 — Save Report (if --save)

If --save was passed, write findings to a date-prefixed file:

# Format: YYYY-MM-DD-refine-report.md

Tell user: > Report saved to YYYY-MM-DD-refine-report.md. This file is gitignored by default.

Verify .gitignore includes *-refine-report.md or similar. If not, suggest adding it.

If --compare was passed, show only findings not present in the comparison report. Findings are matched by file path and description prefix.

---

Invocation Examples

# Prompted for tier
/project-refine

# Explicit tier
/project-refine --tier 2

# Specific domains
/project-refine docs --tier 1
/project-refine code --tier 3

# Save report
/project-refine --tier 3 --save

# Compare with previous report
/project-refine --compare 2026-03-15-refine-report.md

---

Common Pitfalls

| Mistake | Why It's Wrong | Fix | |---------|----------------|-----| | Using severity language (CRITICAL/HIGH) | project-refine never blocks — that's project-health | Use bloat scores (🔴🟡🟢) only | | Rating small-change findings as B or C because the change is small | Size and impact are independent — a two-sentence fix that corrects wrong documentation is 🟢A | Run the self-check: "does fixing this significantly change how quickly someone understands this, or prevent them acting on wrong info?" If yes → A | | Auto-applying refine findings | All are judgment calls requiring human decision | Present opportunities only; never apply without explicit user request | | Running code domain at tier 1 without reading files | Can miss duplication that isn't obvious from structure | Acknowledge tier 1 limitations; recommend tier 2+ for code findings | | Checking tests in a separate domain from code | Tests are code — duplication patterns apply equally | Apply all code checks to test files as well | | Flagging small files as bloated | Size alone is not bloat | Only flag when content is also redundant or over-explained | | Running refinement before health check | Improving something broken is wasted effort | Recommend /project-health first if health status unknown |

---

Success Criteria

Refinement session is complete when:

• ✅ Tier confirmed (via flag, configuration, or prompt)
• ✅ Focus path established (user input or automatic selection)
• ✅ Scan candidates identified at the appropriate tier
• ✅ All applicable domains checked
• ✅ Findings rated with bloat scores (🔴🟡🟢 × A/B/C)
• ✅ Domain summary presented
• ✅ Findings presented as opportunities (no auto-apply)
• ✅ Report saved if --save was passed

Not complete until all configured domains checked and findings presented.

---

Skill Chaining

Invoked by:

• User says "bloat check", "find duplication", "improve docs structure", "refine session", or invokes /project-refine
• Typically run after /project-health when health is green

Does not chain to other skills — refinement findings are advisory and the user decides what to act on independently.

Companion skill:

• [project-health] — run first to verify correctness before improving things.

Shares the same CLAUDE.md ## Health Check Configuration section.

Suggested workflow:

# 1. Verify correctness first
/project-health --prerelease

# 2. Once health is green, look for improvement opportunities
/project-refine

# Or for a full pre-release review
/project-health --deep
/project-refine --tier 3

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mdproctor
• Source: mdproctor/cc-praxis
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.