effort-optimizer

Files (2)

• SKILL.md
• analyze_effort.py · scripts/

SKILL.md (first lines)

# Effort Optimizer

Optimize Claude API costs by matching thinking effort to task complexity. Critical tasks get maximum reasoning; repetitive patterns get minimal overhead.

## Task Categories & Effort Levels

| Category | Effort | Tokens | When to Use |
|----------|--------|--------|-------------|
| `database.schema` | high | max | Table design, migrations |
| `database.rls` | high | max | Security policies |
| `database.indexes` | medium | balanced | Performance optimization |
| `types` | medium | balanced | Type definitions |
| `validation` | medium | balanced | Zod schemas |
| `service` | medium | balanced | Business logic |
| `api.routes` | low | minimal | CRUD endpoints |
| `api.actions` | medium | balanced | Server actions |
| `frontend.components` | medium | balanced | React components |
| `frontend.forms` | medium | balanced | Form handling |
| `frontend.pages` | low | minimal | Page composition |
| `tests.unit` | low | minimal | Unit tests |
| `tests.integration` | medium | balanced | Integration tests |
| `tests.e2e` | low | minimal | E2E tests |

## Usage

### Categorize a Sub-Story

Run `scripts/categorize_task.py`:

```bash
python scripts/categorize_task.py "Create RLS policies for posts table"
# Output: { "category": "database.rls", "effort": "high" }
```

### Analyze PRD for Effort Distribution

```bash
python scripts/analyze_effort.py specs/1-posts-crud/prd.json
```

Output:
```json
{
  "summary": {
    "high": 3,
    "medium": 10,
    "low": 6
  },
  "estimated_savings_pct": 35,
  "stories": [
    { "id": "US-000-1", "category": "database.schema", "effort": "high" },
    { "id": "US-001-1", "category": "api.actions", "effort": "medium" }
  ]
}
```

### Generate Frontmatter Suggestions for Skills

Scan all SKILL.md files and suggest `effort` frontmatter values based on each skill's name and description:

```bash
python scripts/analyze_effort.py --generate-frontmatter skills/
```

Output flags mismatches between current and suggested effort levels:
```json
{
  "total_skills": 33,
  "suggested_distribution": { "high": 5, "medium": 20, "low": 8 },
  "mismatches": 2,
  "skills": [
    { "name": "ralph-loop", "current_effort": "high", "suggested_effort": "high" },
    { "name": "speckit-specify", "current_effort": "medium", "suggested_effort": "medium" }
  ]
}
```

## Relationship with Native `effort` Frontmatter

Claude Code now supports `effort` frontmatter natively in SKILL.md files:

```yaml
---
name: my-skill
effort: low   # low | medium | high
---
```

All 33 skills in this project already have this frontmatter set. The two mechanisms are complementary:

| Scope | Mechanism | What It Controls |
|-------|-----------|-----------------|
| **Skill-level** | `effort` frontmatter in SKILL.md | Default thinking effort when Claude executes a skill |
| **Task-level** | effort-optimizer analysis | Per-story effort in a PRD, used by Ralph++ agents |

The frontmatter sets a static default per skill. The effort-optimizer does dynamic analysis: given a PRD with N sub-stories, it categorizes each one and assigns effort levels based on content, enabling cost optimization across a full implementation run.

### Mapping: Task Categories to Frontmatter Values

If you want to set frontmatter for a new skill based on its dominant task type:

| Dominant Category | Suggested Frontmatter `effort` |
|-------------------|-------------------------------|
| `database.schema`, `database.rls` | `high` |
| `service`, `validation`, `api.actions`, `frontend.components`, `frontend.forms`, `tests.integration` | `medium` |
| `api.routes`, `frontend.pages`, `tests.unit`, `tests.e2e` | `low` |

Use `--generate-frontmatter` with `analyze_effort.py` to scan SKILL.md files and suggest effort values (see below).

## Integration with Ralph++

In `ralph-agent-teams`, effort tuning is applied per sub-story:

```python
# In team orchestrator
effort = get_effort_for_story(story)
agent_config = {
    "thinking": effort,  # "high" | "medium" | "low"
    "max_tokens": EFFORT_TOKENS[effort]

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge