WELL Tracker

Overview

Build a WELL v2 (Q4 2020 + Feb 2023 errata) scorecard for a project. The user declares pursuit status for each Precondition and Optimization; this skill computes the running point total and predicts the certification level. Output is a CSV (one row per feature) plus a markdown summary in docs/well/. This replaces the manual scorecard pass at every project's pre-design phase, kept evergreen through CD and operations handover.

This skill does not decide whether a feature is achievable for a project — that is a strategy call by the WELL AP and the design team. The skill organizes the structure, performs the arithmetic, cites the feature matrix verbatim from references/, and flags features the user has not yet committed on.

When to use

Trigger on:

• "Make a WELL scorecard for this project."
• "Score this project for WELL v2."
• "Update the WELL tracker — we just confirmed N02 is in."
• Pasted wellness/health targets ("project targets WELL Gold — track progress").

Do NOT trigger on:

• "What features can my project earn?" — that's a strategy question, not a tracker request.
• WELL v1 — out of scope (different feature list).
• WELL Performance / Health-Safety / Equity / Community ratings — separate IWBI products.
• LEED, Fitwel, Living Building Challenge — those have separate trackers in the catalog.

Workflow

Step 1 — Bootstrap if needed

Check whether docs/well/index.md exists. If not, run:

python scripts/init_workspace.py

The script creates docs/well/ and an empty tracker log. No external Python dependencies. Confirm with the user before bootstrapping if docs/ does not already exist.

Step 2 — Confirm rating system

State explicitly to the user:

"This skill scores against WELL v2 (IWBI Q4 2020 + Feb 2023 errata, 100 base points + 10 Innovation = 110 max; Bronze 40 / Silver 50 / Gold 60 / Platinum 80). If your project is on WELL v1, WELL Performance, WELL Health-Safety, WELL Equity, or WELL Community, this skill is the wrong tool. Continue?"

Do not proceed silently if the user has not confirmed the rating system.

Step 3 — Gather project context

Read docs/project.md if present. Otherwise ask the user for:

• project_name
• target_certification_level ("Bronze" / "Silver" / "Gold" / "Platinum" / "TBD")
• phase ("pre-design" / "SD" / "DD" / "CD" / "construction" / "operation")
• space_type ("New & Existing Buildings" / "New & Existing Interiors" / "Core") — affects which features are required vs eligible

Step 4 — Initialize a fresh scorecard, or update an existing one

If a scorecard CSV exists at docs/well/<project-slug>-well-scorecard.csv, load it and present current totals before editing. Otherwise initialize from assets/well-v2-scorecard-template.csv, which is pre-seeded with every feature's name, concept, max-points, and Precondition flag — sourced from references/well_v2_features.md.

Before walking the scorecard, instruct the user:

"The bundled scorecard reflects IWBI's published WELL v2 scorecard as of 2026-05-09. For final project documentation, cross-check the per-feature max points against the current IWBI scorecard at standard.wellcertified.com — IWBI publishes amendments quarterly."

Step 5 — Walk the feature list with the user

For each Optimization, the user declares one of:

• Yes — committed to pursuit; counts toward score.
• Maybe — under consideration; counted only in the optimistic total.
• No — not pursuing; zero contribution.
• N/A — not applicable to this project's space type.

For Optimizations with multi-part scoring (e.g. tiered point options), the user states the points-attempted; the skill verifies that against the max published in references/.

For Preconditions (P), they must be Yes or N/A. If marked N/A, the user must justify; if No, the project is non-compliant for any WELL certification — flag.

Step 6 — Compute scores

Run:

python scripts/compute_score.py \
  --scorecard docs/well/<project-slug>-well-scorecard.csv \
  --out docs/well/.cache/<project-slug>-score.json

The script computes:

• Committed points (Yes only).
• Optimistic points (Yes + Maybe).
• Predicted certification level for both totals using the WELL v2 thresholds (40 / 50 / 60 / 80).
• Per-concept subtotals (with WELL's per-concept cap enforced).
• Precondition status (all met / failures listed).

The script reads thresholds and max points from references/well_v2_features.md — never hard-coded into the script.

Step 7 — Write the markdown summary

Beside the CSV, write docs/well/<project-slug>-well-summary.md:

• Header with project name + target + phase + space type + last-updated date.
• Committed total, optimistic total, predicted cert level for each.
• Per-concept subtotal table.
• List of features marked Maybe (next-decision queue).
• Precondition compliance status.
• Citation footer: standard version (WELL v2 Q4 2020 + Feb 2023 errata), reference file path, IWBI source URL.

Step 8 — Update the project WELL index

Run:

python scripts/append_to_index.py \
  --date 2026-05-09 \
  --project "<project-slug>" \
  --target "<Bronze|Silver|Gold|Platinum>" \
  --phase "<phase>" \
  --committed <committed-points> \
  --optimistic <optimistic-points> \
  --cert-predicted "<level>" \
  --csv "<project-slug>-well-scorecard.csv" \
  --summary "<project-slug>-well-summary.md"

Appends a row to docs/well/index.md. Do NOT edit index.md with Edit.

Step 9 — Report

Tell the user:

• Path to scorecard CSV + summary.
• Committed / Optimistic point totals + predicted cert level for each.
• Top 5 features marked Maybe (highest-leverage decisions).
• Any Precondition concerns.
• Reminder: this is structural tracking, not eligibility judgment — verify each Yes against the IWBI WELL v2 standard's feature-specific verification documentation.

Rules

• Every row in the scorecard CSV must reference a feature that exists in references/well_v2_features.md. No invented features.
• Max points per feature are quoted from the references file; the skill never increases a feature's max.
• Certification thresholds come from references/well_v2_features.md, never from training data.
• Score arithmetic runs through compute_score.py, never inline math by Claude.
• Output files live in docs/well/ of the user's project.
• Standard version (WELL v2 Q4 2020 + Feb 2023 errata) and last-verified date are reported in every summary.

Anti-patterns

• Adding a feature not in references/. If the user asks about a feature by a code/name not in the references, treat as user typo and propose the closest match — do not invent.
• Letting the user record more points than the feature's max.
• Predicting a higher cert level than the thresholds support.
• Recommending which features to pursue. This skill is structural — strategic feature selection belongs to the WELL AP.
• Editing docs/well/index.md directly with Edit.
• Treating WELL v1, WELL Performance, WELL Health-Safety, WELL Equity, or WELL Community as scoreable here — they are different IWBI products.

Resources

• scripts/init_workspace.py — bootstrap docs/well/
• scripts/compute_score.py — sum points, evaluate cert level, validate against references
• scripts/append_to_index.py — append a row to docs/well/index.md
• references/_provenance.md — source, version, last-verified
• references/well_v2_features.md — full feature list with point values, Preconditions, thresholds, concept caps
• references/well_concepts.md — concept structure, point allocation per concept
• assets/well-v2-scorecard-template.csv — pre-seeded scorecard (one row per feature)
• assets/well-index-template.md — header table for docs/well/index.md