bmc-holistic-project-health

Evidence-based holistic snapshot of Calculadora BMC: project status from PROJECT-STATE, architecture areas (Vite SPA, Express API, Sheets/MATRIZ, ML/Shopify, Drive, Postgres, hub UI, GPT/MCP, CI), hea

SKILL.md

GitHub

BMC Holistic Project Health — Calculadora BMC

Single runbook for a cross-cutting status report: what the repo says, what checks proved this run, and what to do next—without duplicating deploy or full-team orchestration.

Hard rules

  1. Evidence only: Prefer docs/team/PROJECT-STATE.md (header Última actualización, Cambios recientes, Pendientes if present), then root AGENTS.md, CLAUDE.md, README.md, docs/google-sheets-module/README.md, docs/bmc-dashboard-modernization/DASHBOARD-INTERFACE-MAP.md. For capabilities vs code: docs/api/AGENT-CAPABILITIES.json (regenerate with npm run capabilities:snapshot when needed; manifest in server/agentCapabilitiesManifest.js).
  2. No secrets: Never paste .env values, tokens, or private URLs. Reference variable names only (see .env.example).
  3. No fabrication: Do not assert prod OAuth, Sheets row counts, or CRM state without doc quote or command output from this run. If a check was not run, write unknown — verify with: <command>.
  4. 503 semantics: Per AGENTS.md, many upstream gaps surface as 503 (Sheets/IA unavailable)—do not relabel as generic “500” for Sheets.

When to use

  • User asks: project health, holistic status, architecture map, readiness %, “where are we”, executive snapshot, interpret last smoke:prod / gate, or documented next steps per area.
  • After a large merge or before a stakeholder update (read-only narrative + optional checks).

Delegate — do not duplicate

Need Follow
Deploy, Cloud Run/Vercel rollback, env sync bmc-calculadora-deploy-from-cursor
Local vs prod verification pipeline, §4 propagation bmc-cross-sync-propagation
Update PROJECT-STATE / full team / §4 protocol bmc-project-team-sync, PROJECT-TEAM-FULL-COVERAGE.md
npm command reference Root AGENTS.md

Architecture areas (inventory checklist)

Use this list as rows in the output table; adjust labels if the repo grew—cite CLAUDE.md / server/index.js for new routes.

Area Primary paths / docs
Frontend Vite SPA src/, PanelinCalculadoraV3_backup.jsx, src/data/constants.js, src/utils/calculations.js
Express API server/index.js, server/config.js, server/routes/*
Sheets / MATRIZ / CRM server/routes/bmcDashboard.js, Sheets hub docs, GET /api/actualizar-precios-calculadora
ML / Shopify / webhooks server/routes/ + .env.example entries
Drive / GCS / PDF .env.example, server/routes/pdf.js (and related)
Postgres / Transportista / Omni DATABASE_URL, migrations per AGENTS.md
Hub / Wolfboard / dashboard UI DASHBOARD-INTERFACE-MAP.md, hub modules under src/
GPT / MCP / OpenAPI docs/openapi*.yaml, docs/api/AGENT-CAPABILITIES.json, npm run mcp:panelin
CI / quality .github/workflows/ci.yml, npm run gate:local*
Docs / team process PROJECT-STATE.md, PROJECT-TEAM-FULL-COVERAGE.md

Procedure (each run)

  1. Scope: Note branch/commit (git status -sb, git log -1 --oneline) if available.
  2. Read docs/team/PROJECT-STATE.md — capture Última actualización and the most relevant Cambios recientes bullets (last few).
  3. Health checks (execute or explicitly mark skipped with reason):
Command Pass criteria
npm run smoke:prod Exit 0; script reports /health, /capabilities, public_base_url alignment, and MATRIZ CSV unless skipped per AGENTS.md (SMOKE_SKIP_MATRIZ, -- --skip-matriz)
npm run gate:local ESLint clean on src/; npm test exit 0
npm run gate:local:full Gate local + npm run build exit 0
curl -sS http://localhost:3001/health After npm run start:api: HTTP 200, JSON ok: true
npm run test:contracts With API on 3001: validator exit 0
npm run ml:verify When ML env configured: script exit 0
  1. Readiness %: Apply the legend below to each architecture row. Lower the score for any unknown critical check.
  2. Risks: Only items evidenced by PROJECT-STATE, failing commands, or linked human gates (docs/team/HUMAN-GATES-ONE-BY-ONE.md).
  3. Deliverable: Fill the Output template (next section). Optionally write docs/team/reports/PROJECT-HEALTH-SNAPSHOT-YYYY-MM-DD.md when the user wants a tracked snapshot.

Readiness legend (required for every %)

  • 100%: Smoke + gate:local:full green this run, docs explicitly aligned, no evidenced blockers for that area.
  • 85–99%: Core checks green; minor gaps (optional E2E not run, non-critical doc lag).
  • 70–84%: Partial verification or some checks skipped; dependencies on secrets/human gates documented.
  • 50–69%: Known partial failures or unverified critical path for that area.
  • Below 50%: Broken critical path for that area or no safe evidence—list verification commands.

Output template

Executive summary

5–8 sentences: posture, what changed recently (cite PROJECT-STATE dates), whether smoke/gate ran and passed this run, top 1–3 risks with evidence.

Architecture map table

Area Responsibility Evidence Status Readiness % Objective Impact Next steps
… … path or doc § one line use legend one line one line bullet(s)

Health checks table

Command Result this run Notes
… pass / fail / skipped excerpt or “not executed”

Recent developments

Bullets citing dated PROJECT-STATE Cambios recientes (optional git log -5 --oneline—flag if it diverges from PROJECT-STATE).

Risks / blockers

Evidence-only list.

Anti-duplication

Keep this file as the index. For deploy steps, OAuth gates, or orchestrator order, follow the delegated skills above.