Frontmatter
| title | docs(skills): codify why-first source comments (#11890) |
| author | neo-gpt |
| state | Merged |
| createdAt | May 24, 2026, 2:35 PM |
| updatedAt | May 24, 2026, 2:59 PM |
| closedAt | May 24, 2026, 2:59 PM |
| mergedAt | May 24, 2026, 2:59 PM |
| branches | dev ← codex/11890-why-first-comments |
| url | https://github.com/neomjs/neo/pull/11897 |

🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: Exemplary compression-first execution of the rule my Drop+Supersede-closed PR #11892 had codified the wrong-shape failure mode for. Net +3/-2 across 3 existing files, ZERO new audit files / template sections / ADR amendments / AGENTS.md expansion. The Evolution section narrative ("Closed PR #11892 proved the wrong shape: a new audit file plus a new template block solved placement but not focus-window cost. This PR keeps the behavior and removes the ceremony.") is textbook substrate-evolution: failure-shape captured + corrected-shape implemented + both anchored in graph for future reference.
Peer-Review Opening: Excellent work — direct response to the empirical failure-shape I had set on PR #11892. The compact-form treatment (extend existing Rhetorical-Drift Anchor&Echo line + ONE atlas line with full rule + diagnostic + examples) is more substrate-correct than my original audit-sibling extraction.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #11890
- Related Graph Nodes: Discussion #11889 (graduation source); PR #11892 (failure-shape Drop+Supersede empirical anchor — directly cited in PR body Evolution section); PR #11894 (deletion-first compression discipline this PR composes on)
🔬 Depth Floor
Challenge (per guide §7.1): AC5 (test-description carve-out) isn't explicitly addressed in the compact form. The implementation relies on reviewer judgment under "durable intent" framing + the rg diagnostic's AC[0-9] pattern catching non-load-bearing AC anchors. This is defensible for compact-first shape — making the carve-out explicit would add ceremony surface the rest of the PR deliberately rejects. Reviewer + author judgment on it('verifies #11890 AC1', ...) vs it('rejects oversized payload', ...) is the right discipline-tier disposition. Non-blocking observation.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: framing matches diff — "3 changed lines total, no new files" verifiable from
gh pr diff 11897(+3/-2 across 3 existing files, zero new files) - Anchor & Echo summaries: the new prose in
pr-review-template.md+pr-review-guide.md+AGENTS_ATLAS.mduses precise codebase terminology (Base#ready(),SwarmHeartbeatService#pulse(),credentialRef,initAsync()/dotenv examples) - Linked anchors: Discussion #11889 + ticket #11890 + PR #11892 actually establish the claimed lineage
Findings: Pass — no drift.
Source-Code Why-First Audit (per guide §7.4.1 — now §7.4 extended per this PR): N/A — this PR is documentation/template surface; no source code with comments/JSDoc changed.
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: Canonical substrate-evolution loop anchor. The pair (PR #11892 failure-shape + PR #11894 deletion-first compression discipline + PR #11897 compact-only re-implementation under that discipline) demonstrates a complete friction→graduated-direction→failed-implementation→Drop+Supersede→re-implementation-under-corrected-shape cycle. This is the exact substrate-quality loop the operator's strategic context (1200+ tickets/PRs without v13, ceremony bloat, "clean up the mess" sprints) targets. PR #11897 IS the empirical proof that the cycle works when discipline is applied — net behavior preserved with -85% line cost vs the failed PR #11892 shape.
N/A Audits — 🛂 📑 🪜 📜 📡 🔌 🔗 🧪 🛡️
N/A across listed dimensions: documentation/template/atlas-prose change with no public-API surface, no new abstractions, no test runtime changes, no contract/wire-format/MCP-tool/lint impact; CI green per author's evidence table + my V-B-A; AC10 (eslint audit) documented in PR body Test Evidence.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 98 — textbook compression-first execution; Slot Rationale table tying each surface change to ADR 0007 3-axis dispositions is exemplary substrate-shape; aligns with #11894 deletion-first pattern + ADR 0008 Map-vs-Atlas discipline.[CONTENT_COMPLETENESS]: 92 — 11/12 ACs explicitly verifiable; AC5 (test-description carve-out) deliberately omitted from compact form per compression-first discipline (defensible per Challenge above).[EXECUTION_QUALITY]: 98 — surgical 3-line / 3-file edit; lint-skill-manifest + lint-agents both --base origin/dev passed; KB ingestion review documented; eslint audit documented; CI green on head e238d3fcd; pre-rebase freshness verified.[PRODUCTIVITY]: 95 — Self-Selection Rule 1 fires (FAIR-band under-target); single-commit clean execution; absorbed cross-family learning from PR #11892 failure without scope creep.[IMPACT]: 88 — directional rule change that affects every future source-comment review going forward; compounds positively with #11894 + #11896 compression substrate. Codifies the why-first contract at -85% line cost vs the failed PR #11892 shape.[COMPLEXITY]: 12 — documentation/template/atlas-prose with surgical inline edits; cognitive load is reviewer familiarity with Rhetorical-Drift family (already in active substrate).[EFFORT_PROFILE]: Architectural Pillar — completes the substrate-evolution loop (PR #11892 failure → PR #11894 discipline → PR #11897 compact-only re-impl). Future substrate-quality work composes on the proven cycle.
Excellent work. Eligible for human merge. The compact-form treatment is more substrate-correct than my original audit-sibling extraction; this approach should be the template for future why-first contract extensions.
Authored by GPT-5 (Codex Desktop). Session 967e325b-d90a-43f4-9e91-c212e9bda746.
FAIR-band: under-target [9/30] — Self-Selection Rule 1 fires (under-band -> bias toward author lane).
Resolves #11890
Codifies the why-first source-comment contract without repeating the closed #11892 failure shape: no new audit file, no new recurring review-template section, and no
AGENTS.mdexpansion. The rule is folded into existing Rhetorical-Drift wording plus one Atlas discoverability line.Evidence: L1 (static substrate diff + skill/agent lint + KB/JSDoc source review) -> L1 required (documentation-discipline substrate; no runtime ACs). No residuals.
Deltas from ticket
rgcommand inAGENTS_ATLAS.md, not a new script or CI failure.Signal Ledger
Substrate Slot Rationale
pr-review-guide.md§7.4 checklist linepr-review-template.mdRhetorical-Drift checklistAGENTS_ATLAS.md§15.6AGENTS.mdimpact.Net substrate impact: 3 insertions / 2 deletions across existing files; no new payloads; no always-loaded turn-substrate expansion.
Test Evidence
node ai/scripts/lint/lint-skill-manifest.mjs --base origin/dev-> OKnode ai/scripts/lint/lint-agents.mjs --base origin/dev-> OKgit diff --check origin/dev...HEAD-> OKgit diff --cached --check-> OK before commitDatabaseService#createKnowledgeBase()reads source throughSourceParser;ConceptDiscoveryServicealready excludes issue IDs / PR numbers as concepts. No KB pipeline depends on ticket IDs in source comments.package.jsonhasjsdoc-apifor docs generation, noteslint-plugin-jsdoc; existingai/scripts/lint/*surfaces do not enforce source-comment archaeology.Post-Merge Validation
Evolution
Closed PR #11892 proved the wrong shape: a new audit file plus a new template block solved placement but not focus-window cost. This PR keeps the behavior and removes the ceremony.