Skip to content

hmr-BH/HMAP

human-maintainability

Verified

Assess a programming project's HUMAN maintainability (HMAP): 0-100 score, nine-tier verdict, per-dimension scores, and file:line evidence — built to catch vibe-coding / AI-generated slop, including semantic incoherence (name/contract/concept/vocabulary drift). Triggers: assess maintainability / rate this project / code quality score / readability score / AI slop detection / vibe coding check / semantic consistency check / HMAP / human maintainability / 评估项目可维护性 / 给项目打分 / 代码质量评估 / 可读性评分 / AI屎山检测 / vibe coding 体检 / 是否适合人类维护 / 语义一致性. Anti-trigger: the user asks to fix, refactor, optimize, or write code — that is a different task; this skill only assesses, never modifies.

---
name: human-maintainability
version: 1.1.2
description: "Assess a programming project's HUMAN maintainability (HMAP): 0-100 score, nine-tier verdict, per-dimension scores, and file:line evidence — built to catch vibe-coding / AI-generated slop, including semantic incoherence (name/contract/concept/vocabulary drift). Triggers: assess maintainability / rate this project / code quality score / readability score / AI slop detection / vibe coding check / semantic consistency check / HMAP / human maintainability / 评估项目可维护性 / 给项目打分 / 代码质量评估 / 可读性评分 / AI屎山检测 / vibe coding 体检 / 是否适合人类维护 / 语义一致性. Anti-trigger: the user asks to fix, refactor, optimize, or write code — that is a different task; this skill only assesses, never modifies."
---

# human-maintainability (HMAP)

Human Maintainability Assessment of Programming Projects — scores whether a project is maintainable by **human programmers** (0-100, nine tiers), with dedicated forensics for vibe-coding / AI-generated slop.

**Core principle: assess only, never modify.** No refactoring, no bug fixes, no touching source files; findings go into the report, period.

## Trigger / anti-trigger

- **Trigger**: the user asks to "assess maintainability / score this project / check for AI slop / rate code quality / is it human-maintainable" for any path, with the target given or inferable.
- **Anti-trigger**: the user wants bugs fixed, refactoring, features, or performance work — do NOT apply this skill. If asked to "assess then fix", finish the assessment first; handle fixes only under a new instruction.

## Scoring model (4 weighted dimensions, 100 max)

> **Read before scoring**: this is a **human readability & maintainability** assessment, not a style-compliance review — comment coverage, naming consistency, DRY and similar "standards" earn no points by themselves, only when they serve human understanding and maintenance. **Core question**: after reading the code, ask yourself "if this project were handed to you, would you maintain it yourself? Why?" The total score must agree with the answer.
>
> **Black cat, white cat — equal treatment**: AI authorship, project size, and maintainer count are NEVER scoring criteria — only whether the artifact obstructs human maintenance. READMEs are checked only for promise fulfillment (tidiness/ads/marketing/absence are not penalized).
>
> **Use the full 0-100 range**: human-normal debt alone never fails a project (debt floors D2/D4 at 70; good projects with only debt land 80+), and the 0-40 bands are real landing zones — a slop pile (gods + fingerprints + broken promises + unreadable) SHOULD total 20-40. Do not cluster everything at 45-80.

| Dimension | Weight | Key question |
|---|---|---|
| D1 Design soundness & technical honesty | 25 | Does the architecture match the problem's complexity? Do promises survive code verification? Real engineering thinking (measurement/trade-offs) or wishful thinking? Do tests give maintainers safety? |
| D2 Traceability & mental load | 30 | Can a human trace request → code? Clear responsibilities or everything fused together? Change one thing — how many places must you know? Must the structure be memorized via external docs? |
| D3 Human readability & self-explanation | 15 | Does the code explain itself? Do names/comments convey "why", or are they decorative / written for AI? |
| D4 AI slop & wishful-thinking residue (reverse) | 30 | Promise betrayal, over-engineering, source-inlined AI process markers, structural gods (big AND mixed), systemic copy-paste, debug residue, hallucinated comments — more residue, lower score |

Score each dimension 0-100, weight-sum, then apply structural hard gates. Semantic coherence (names telling the truth, contracts closed, concepts single-sourced, vocabulary self-evident) is audited by the fixed SCA protocol (M14) and feeds all four dimensions — it is the third evaluation axis alongside structure and residue. **Detailed rules (M1-M16 measurement table, tier mapping, SCA semantic-coherence protocol, RM responsibility-mixing protocol, tie-breaks): [`references/scoring-rubric.md`](references/scoring-rubric.md); signal catalog: [`references/ai-slop-signals.md`](references/ai-slop-signals.md); worked scoring example: [`references/golden-example.md`](references/golden-example.md).**

> **Structural hard gates (pass-line verdicts)**: structural facts that make human maintenance impossible or infeasible hard-cap the total — core god-function/god-file that is also responsibility-mixed → **60** (pass-line edge); source-inlined AI process markers at scale → **45**; AI debugging residue in hot paths ≥5 (coordinate/offset special-cases, magic offsets, embedded debugging narratives, probe residue; **ordinary bare printlns excluded**) → **45**; **G1 together with G3/G4 → 40**. Dimension scores may not lift the total above a cap. **Gates judge structure only — never size, headcount, or AI authorship**; top-level convention files (AGENTS.md/CLAUDE.md etc.) are not AI process markers.

## Nine tiers (60 is the split: ≥60 pass = human-maintainable; <60 fail = unfit for direct human maintenance)

| Range | Verdict |
|---|---|
| 90-100 | **Ideal**: clear responsibility boundaries, request→code traceable, comments explain "why", all promises kept |
| 80-90 | **Smooth**: generally fluent, only acceptable debt; **no structural mixing, no AI fingerprints at scale** |
| 70-80 | **Burdened**: cross-file tracing costs, a few bloated spots, or minor AI traces |
| 60-70 | **Pass-line edge**: visible AI-slop traces or structural bloat emerging (god-file/bloated functions); takeover is hard but humans can still maintain it |
| 50-60 | **Fail — unfit for direct human maintenance**: severe responsibility mixing, poor readability; takeover cost disproportionate |
| 40-50 | **Unfit**: core bloated, structure untraceable; external docs/AI required to understand |
| 30-40 | **Unfit (heavier)**: structural gods rampant; humans cannot change code safely |
| 20-30 | **Extremely unfit**: structural gods + AI process fingerprints everywhere |
| 0-20 | **AI-agent-only**: total slop, beyond rescue |

Boundary semantics: `>=90` lands in the 90 tier; and so on; `<20` in the 0 tier.
**The 60 split is this skill's anchor**: ≥60 = pass = a human programmer can maintain it (matching cent exam intuition); <60 = fail = unfit for direct human maintenance. Tier descriptions encode the "can humans maintain it" judgment, not surface quality — structural mixing lands below 60; AI fingerprints at scale land below 60.

## Assessment workflow

**Before starting you MUST read** [`references/scoring-rubric.md`](references/scoring-rubric.md), [`references/ai-slop-signals.md`](references/ai-slop-signals.md), and [`references/golden-example.md`](references/golden-example.md) to align scoring lenses and calibration.

### Step 1: parse arguments

- **Target path** (required): the project directory, relative or absolute; defaults to the current working directory.
- `--depth=light|medium|deep` (optional): sampling intensity. Default medium.
- `--output=path` (optional): write the full report to the given markdown file.
- `--focus=dimension` (optional): assess only the named dimension (D1 design / D2 traceability / D3 readability / D4 slop); no total score.

### Step 2: inventory

Glob / Grep / Bash: total file count and file tree (exclude dependency & build dirs: `node_modules`, `.git`, `dist`, `build`, `venv`, `target`, `__pycache__`, `.next`, `bin/Release`, `obj`, etc.); language mix and estimated total LOC; locate README, build/package entry, entry file, test directories.

### Step 3: sampling protocol

Sample and **declare the sampling scope and confidence**. Unread files must not be scored as if read.

| Project size | Sampling strategy | Default reads |
|---|---|---|
| ≤50 source files | read all | all |
| 50-500 | entry + core modules + per-layer representatives + largest files + most-commented files | 15-30 files |
| >500 | stratified sampling: entry, business core, boundary/infra | 30-60 files |

Must-read regardless of size: README, build/package entry, entry file, largest source file, most recently modified files. `--depth=deep` doubles the read count; `--depth=light` halves it. **Repeated evaluations must fix the same sampling depth.**

### Step 4: per-dimension forensics

- **Measure first (mandatory before scoring)**: run M1-M16 from the rubric's global measurement table and fill the sheet. **Measured values decide tiers — before impressions.**
- **Semantic Coherence Audit (SCA, M14)**: run `references/semantic-surface.py <root>` → adjudicate the top-15 most-referenced symbols (SI-1 names), review SI-2/SI-3/SI-4 candidates against the exclusion rules, run the 20-site convention census (CV); record `SI1_viol / SI2_unconsumed / SI2_trap / SI3_pairs / SI4_unrooted / CV` in the sheet. Never adjudicate by impression.
- **Promise verification (mandatory)**: list README/doc promises → verify each in code (claiming "performance gains" while only adding abstraction layers, claiming "extensible" with no extension points ⇒ major wish evidence). README: promises only; tidiness/ads/absence not penalized.
- **Responsibility mixing via the RM protocol**: every ≥400-line function / ≥1800-line file goes through RM (enumerate domains → count → precedents → arbiter) for "single responsibility vs mixed". Big-but-single is not penalized; bloat is.
- **Boundary decisions**: when a measurement lands on a boundary or signals conflict, record a boundary decision per rubric rule 8 (object / both-side reasoning / final choice / evidence) — no systematic rounding to either side.
- Every scoring judgment must land on `file:line` evidence; impressions without evidence may not be used.

### Step 5: weighted scoring & structural gates

- Per the rubric's measurement→anchor tables: tier per dimension → enumerated adjustments → four raw scores.
- Weighted total = 0.25×D1 + 0.30×D2 + 0.15×D3 + 0.30×D4; apply hard gates (G1/G3/G4; multiple hits → lowest cap).
- **Forced judgment**: honestly answer "would you maintain it yourself? Why?" — "no" ⇒ total ≤60, "absolutely not" ⇒ ≤40. If the answer says so but the total hasn't reached the cap, you were dazzled by surface discipline (tests/CI/docs) — lower it.
- **60-split check (mandatory, the anchor)**: answer "which side of the 60 line — ≥60 pass (human-maintainable) or <60 fail (unfit)?" A <60-side answer with total ≥60 ⇒ the mechanical score was fooled by surface quality — **force it below 60**; a ≥60-side answer with total <60 ⇒ recheck measurements. **On conflict, the answer wins.**
- Map the total to the nine tiers; round to integer.
- **Scoring discipline**: evidence-based, neither inflated nor soft; declare low confidence when evidence is thin; totals differing by >3 across two evaluations ⇒ run the rubric's consistency self-check — no bargaining.

### Step 6: report

- **Output language rule (mandatory): the final report MUST be written in the same language as the user's input** (user writes Chinese ⇒ report in Chinese; English ⇒ English; and so on). The skill text itself is English; this rule governs only the delivered report.
- Default: full report in the conversation. With `--output`: a condensed version in the conversation, the full report written to the file — state the path.

## Report template

```markdown
## HMAP Report: <project name> (<target path>)

**Total: XX/100 — <tier verdict>**

Scope: N source files, M read (depth: light/medium/deep), confidence: high/medium/low. Measurement sheet: key M1-M16 values (≤5 lines).

### Dimension scores

| Dimension | Raw | Weight | Weighted | One-line rationale |
|---|---|---|---|---|
| D1 Design soundness & honesty |  | 25 |  |  |
| D2 Traceability & mental load |  | 30 |  |  |
| D3 Readability & self-explanation |  | 15 |  |  |
| D4 AI slop & wishful residue |  | 30 |  |  |

### Overall assessment

(3-5 sentences: overall impression and main tensions)

### Strengths (evidenced)

- `file:line` — strength

### Key problems (evidenced, most severe first)

- `file:line` — problem

### AI-slop findings

- `file:line` — slop signal (cite the signal number/name from `references/ai-slop-signals.md`)

### Evidence appendix (mandatory)

- Comment sample classification: every sampled comment → I/R/S/H with its classification reason
- T_trace hop lists for the 3 probed journeys; T_impact probe result; D (decorative abstraction) enumeration
- All boundary decisions (object / both-side reasoning / final choice / evidence)

### Conclusion & recommendations

- Fit for human maintenance? (nine-tier verdict)
- If <60: the 1-3 worst concentrations, and whether a human or an AI agent should fix them
- Hard gates hit (if any) + forced-judgment answer
- Optional improvements (suggest only, never implement)
```

## Boundary discipline

1. **Assess only, never modify**: no refactoring, no bug fixes, no touching any source file.
2. **No fabricated evidence**: judgments without `file:line` evidence may not enter the report; verify the cited line exists before citing.
3. **Honest scoring**: the score must be derivable from the measurement sheet and tier tables; declare thin sampling; prefer low confidence over inflation.
4. **Stay in scope**: with `--focus`, assess only that dimension.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall