fix(release): require user-observable surface for minor bumps

[carlos-alm]

Summary

The /release skill was treating any feat: commit outside a fixed list of "internal scopes" as a minor bump. During the v3.9.4 release prep it flagged feat(js-extractor) (#947) and feat(native) (#937) as minor, proposing 3.10.0 — but neither adds any new CLI command, flag, MCP tool, output field, or config option. The first is an extractor accuracy improvement; the second is a perf refactor.

Rewrite Step 1b so the conventional commit prefix is a hint, not the verdict:

• Define the real test for a minor bump — the commit must add a new CLI command, CLI flag, MCP tool, output format/field, config option, or public programmatic API export
• List what is NOT a minor bump even when prefixed feat: — extractor accuracy (→ Bug Fixes), perf refactors (→ Performance), internal plumbing (→ patch)
• Add a decision procedure: read the PR body, ask whether new user-facing surface exists, re-categorize if not
• Require stating the specific new surface before committing to a minor bump — if you cannot name it, the bump is patch

Test plan

• Next release invocation correctly classifies accuracy/perf feat: commits as patch
• Minor bumps are justified with a named CLI surface before proceeding

[claude]

Claude finished @carlos-alm's task —— View job

---

Todo List

• Read and analyze the modified skill file
• Perform root cause analysis
• Check for configuration/test integrity issues
• Evaluate code quality and approach
• Apply backlog compliance rating
• Provide final assessment and recommendation

Root Cause Analysis

Problem Being Solved: The /release skill was incorrectly classifying internal improvements as minor bumps based solely on feat: prefix. Commits like feat(js-extractor): resolve named function references (#947) and feat(native): port full-build structure computation (#937) were flagged as minor despite adding no user-facing CLI surface.

Why This Approach: The fix correctly addresses the root cause by redefining what constitutes a minor bump. Instead of using scope exclusion lists, it requires identifying actual observable user functionality. This is the right approach - the problem was conceptual (wrong classification logic), not implementation.

Risk Assessment: Low risk. This is a process improvement to documentation that will prevent incorrect version bumping. No code changes, just better decision criteria.

Backlog Compliance

• Zero-dep: ✓ — No new dependencies, pure documentation change
• Foundation-aligned: ✓ — Improves release process accuracy, aligns with maintenance excellence
• Problem-fit: 3 — Useful process improvement but doesn't directly address core AI/codegraph navigation problems
• Breaking: No — Documentation-only change with no API/CLI impact
• Tier: 1 (Zero-dep ✓ + Foundation-aligned ✓)

Technical Assessment

Excellent problem diagnosis and solution. The rewrite moves from brittle scope-based exclusions to semantic analysis of actual user impact. Key improvements:

What Makes This Better (.claude/skills/release/SKILL.md:46-101)

1. Concrete criteria (lines 50-57): Lists 6 specific types of user-facing changes that warrant minor bumps

   • New CLI commands/flags
   • New MCP tools
   • New output formats/fields
   • New config options
   • New public API exports

2. Clear counter-examples (lines 59-62): Explicitly categorizes what's NOT minor:

   • Extractor accuracy → Bug Fixes
   • Performance refactors → Performance
   • Internal plumbing → patch

3. Verification procedure (lines 66-72): Requires reading PR bodies and asking whether new user-facing surface exists

4. Mandatory justification (lines 86-101): Forces naming specific new surface before committing to minor bump

Addresses the Root Problem

The problematic commits mentioned in the PR description would now be correctly classified:

• feat(js-extractor): resolve named function references → patch (accuracy improvement, no new CLI surface)
• feat(native): port full-build structure computation → patch (performance refactor, no new commands/flags)

This fixes the exact issue where scope-based exclusions failed to catch feature-prefixed internal improvements.

Code Quality

• No configuration relaxation: ✅ No rules disabled or thresholds lowered
• Clear documentation: ✅ Much more actionable than the previous scope-based approach
• Root cause addressed: ✅ Fixes the underlying logic, doesn't hide symptoms
• Well-structured: ✅ Clear decision tree with concrete examples

Final Assessment

## Root Cause Analysis
**Problem Being Solved**: Release skill incorrectly classifying feat-prefixed internal improvements as minor bumps
**Why This Approach**: Semantic analysis of user impact vs. brittle scope exclusions - correct fundamental fix
**Risk Assessment**: Low - documentation improvement with clear benefits

## Backlog Compliance
- Zero-dep: ✓ — pure documentation change
- Foundation-aligned: ✓ — improves process accuracy
- Problem-fit: 3 — useful but doesn't address core AI navigation problems  
- Breaking: No
- Tier: 1

## Critical Concerns
None. This is a well-reasoned fix to a real classification problem.

## Final Recommendation
- Rating: ⭐⭐⭐⭐☆ (4/5)
- Action: APPROVE
- Reasoning: Correctly diagnoses and fixes the root cause. The new semantic approach is much more robust than scope-based exclusions. Clear examples and verification procedures prevent future misclassification. Minor deduction only because this is process improvement rather than core functionality enhancement.

[greptile-apps]

Greptile Summary

Replaces Step 1b's brittle feat(scope) internal-scopes allowlist with a semantic "real test" — a commit is minor only if it adds a new CLI command, flag, MCP tool, output format/field, config option, or public programmatic API export. A decision procedure, CHANGELOG re-categorization guidance, and worked examples (the feat(js-extractor) / feat(native) v3.9.4 case) are added to keep future release agents grounded.

Confidence Score: 5/5

Safe to merge — logic is sound, the prior P1 concern about missing criterion #6 is resolved, and the one remaining finding is a minor formatting inconsistency.

All remaining findings are P2 style suggestions. The decision procedure is internally consistent across the 6-point real-test list, the priority table, the decision-procedure question, and the "before committing" narrative. No correctness or data-integrity issues.

No files require special attention.

Important Files Changed

Filename	Overview
.claude/skills/release/SKILL.md	Step 1b rewritten to use user-observable surface as the real version-bump criterion; replaces the brittle internal-scopes allowlist with a 6-point checklist, a semantic decision procedure, and concrete examples. One minor inconsistency: the third "NOT minor" bullet omits the CHANGELOG section label that the other two bullets provide.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Scan commits since last tag] --> B{BREAKING CHANGE\nor ! suffix?}
    B -- Yes --> MAJOR[major bump]
    B -- No --> C{feat: or feat scope commit?}
    C -- No --> PATCH[patch bump]
    C -- Yes --> D[Read PR body or commit body]
    D --> E{Passes real test?\nNew CLI cmd / flag /\nMCP tool / output field /\nconfig / public API export}
    E -- Yes --> F[Name the specific surface]
    F --> MINOR[minor bump]
    E -- No --> G{What kind of change?}
    G -- Accuracy fix --> BF[Bug Fixes in CHANGELOG → patch]
    G -- Perf refactor --> PERF[Performance in CHANGELOG → patch]
    G -- Internal plumbing --> CHORES[Chores in CHANGELOG → patch]

Loading

_{Reviews (2): Last reviewed commit: "fix(release): include public API export ..." | Re-trigger Greptile}

[greptile-apps]

Missing criterion in table and inline summaries

The "real test" in lines 50–57 lists 6 criteria, but the summary references in the decision procedure (line 69), table (line 78), and "before committing" narrative (line 96) all reduce it to 5, dropping item 6: a new public programmatic API export from index.ts. An agent relying on any of the three shorthands would silently miss this case.

Suggested change

	| Any `feat:` commit passes the "real test" above (adds new CLI command/flag/MCP tool/output field/config) | **minor** |
	| Any `feat:` commit passes the "real test" above (adds new CLI command/flag/MCP tool/output field/config/public API export) | **minor** |

The same omission appears on lines 69 and 96 — suggest adding "or public API export" to both for consistency.

[carlos-alm]

Fixed in 1aeaff1 — added "public API export" to all three shorthand locations (decision procedure line 69, rules table line 78, and patch-bump narrative line 96) so the shorthand matches the 6-item real-test list above.

[carlos-alm]

@greptileai