# Cost Management

> Skill: Cost Management

- Skill: `gonzalezpazmonica/cost-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add gonzalezpazmonica/cost-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gonzalezpazmonica/cost-management/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gonzalezpazmonica (https://skillmd.com/u/gonzalezpazmonica)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gonzalezpazmonica/cost-management

---


# Skill: Cost Management

> Prerequisito: @docs/rules/domain/billing-model.md, @docs/rules/domain/cost-tracking.md

Orquesta timesheet logging, budget tracking, forecasting y generación de invoices.

## Flujo 1 — Log de horas (`log`)

1. Validar entrada:
   - `date`, `user`, `task_id`, `project`, `hours` (todos requeridos)
   - `hours` es decimal ≥ 0.5
   - `user` tiene perfil
   - `project` existe en `projects/{proj}/CLAUDE.md`
2. Leer rates de `.flow-data/rates.json` (o `.flow-data/{project}/.rates.local.json`)
3. Calcular cost = hours × rate_for_role
4. Crear entrada JSONL en `.flow-data/timesheets/{user}/{YYYY-MM}.jsonl`
5. Actualizar ledger: añadir entrada type "time" a `.flow-data/ledger/{project}.jsonl`
6. Output: confirmación + acumulado del mes

Error handling:
- Horas duplicadas (misma user/task/date): advertir, preguntar si actualizar
- Rate no encontrado: sugerir `/cost-center budget --create-rates`
- User sin perfil: sugerir `/profile-setup {user}`

## Flujo 2 — Informe de costes (`report`)

Parámetros: `--period {YYYY-MM}`, `--team {nombre}`, `--project {slug}`, `--client {slug}`

1. Recopilar timesheet entries según filtros
2. Agregar por:
   - Proyecto
   - Equipo (si `--team`)
   - Cliente (si `--client`)
   - Rol
3. Calcular KPIs: cost-per-SP, utilization-rate, burn-rate
4. Generar tabla resumen:
   ```
   Project     │ Hours  │ Cost (€) │ Team      │ Status
   ────────────┼────────┼──────────┼───────────┼─────────
   sala-reservas │ 160   │ 13,600   │ Backend   │ On-budget
   api-v3      │ 120    │ 14,400   │ Backend   │ 5% over
   ```
5. Guardar en `output/cost-report-{periodo}.md`

## Flujo 3 — Gestión de presupuestos (`budget`)

Subcomandos:
- `--create {project}`: crear presupuesto inicial (solicitar total, moneda, fechas)
- `--update {project}`: modificar presupuesto (total, alerts)
- `--burn {project}`: mostrar burn actual vs. presupuesto
- `--status`: comparar todos los proyectos

Output: tabla con budget/actual/remaining/% spent + alertas

```
Project         │ Total   │ Spent  │ Remaining │ Status
────────────────┼─────────┼────────┼───────────┼──────────
sala-reservas   │ €50,000 │ €42,500 │ €7,500    │ 85% ⚠️
api-v3          │ €60,000 │ €48,000 │ €12,000   │ 80% ⚠️
```

## Flujo 4 — Pronóstico (`forecast`)

1. Leer ledger del proyecto
2. Calcular:
   - `elapsed_days` = hoy - fecha_inicio_presupuesto
   - `burn_rate` = actual_burn / elapsed_days
   - `remaining_days` = fecha_fin_presupuesto - hoy
   - `EAC` = burn_rate × (elapsed_days + remaining_days)
3. Comparar `EAC` vs. `BAC`:
   - Si EAC > BAC: mostrar riesgo y opciones (reducir scope, extender)
   - Si EAC < BAC: proyecto bajo presupuesto

Output: gráfico ASCII de proyección + recomendaciones

```
Forecast: EAC = €55,200 (BAC = €50,000)
Risk: 10.4% over budget
Options:
  1. Reduce scope (descope €5,200 worth of features)
  2. Extend timeline (add 2 weeks)
  3. Increase budget (request €5,200 approval)
```

## Flujo 5 — Generación de invoices (`invoice`)

Parámetros: `--client {slug}`, `--period {YYYY-MM}`, `--status draft|final`

1. Recopilar timesheet entries para cliente + período
2. Agrupar por (project, role)
3. Generar invoice JSON con schema de @billing-model.md
4. Guardar en `output/invoices/{client}-{YYYY-MM}.json`
5. Status = "draft" (editable), cambiar a "final" cuando aprobado
6. Output: resumen + ruta del PDF

## Errores

| Problema | Solución |
|----------|----------|
| Horas duplicadas | Advertir, preguntar si mezclar o descartar |
| Rate no definido | Crear rate primero con `/cost-center budget --create-rates` |
| Proyecto sin presupuesto | Crear presupuesto con `/cost-center budget --create {project}` |
| Período sin datos | Mostrar período más reciente disponible |

## Seguridad

- **Rates are git-ignored**: `.flow-data/rates.json` nunca en commit
- **No PII in invoices**: solo @handles, nunca nombres reales
- **Ledger is immutable**: no editar historial, solo adjustments adelante
- **Auditable**: cada entrada tiene timestamp y user para trazabilidad

