[developer-docs] Developer Documentation Consolidation - 2026-05-30

[github-actions[bot]]

Summary

Weekly maintenance pass over the scratchpad/ developer specifications. The corpus is mature (dev.md is at v9.14 with dozens of prior consolidation runs), so most marketing language was already removed in earlier passes. This run scanned 64 spec files, fixed 2 residual subjective-tone issues, documented 1 recently-merged architectural change, and bumped the consolidated scratchpad/dev.md to v9.15.

• Files scanned: 64
• Tone adjustments: 2
• Mermaid diagrams added: 0 (existing diagrams already cover affected sections)
• New features documented: 1 (safe-output cross-repository handler consistency)
• New spec files: 0
• Status: ✅ Consolidated; PR opened

Tone Fixes

File	Before	After	Rationale
token-budget-guidelines.md:242	"Scans all lock files comprehensively"	"Scans all lock files"	Removed subjective adverb; the file count is the substantive detail (v6.1 comprehensive→removed pattern)
engine-review-summary.md:1	"# Deep Review Summary: ..."	"# Detailed Review Summary: ..."	H1 was a leftover after v9.13 corrected "Completed deep review"→"Completed a detailed review" in the same file's body (v3.8/v9.13 Deep→Detailed pattern)

Documentation Added

In dev.md → Safe Outputs System → Common Configuration Patterns, clarified that target-repo and allowed-repos are honored by all safe-output handlers — including add-labels, remove-labels, and assign-to-user — not only create-issue, and that handler configuration is generated into a single config.json from the handler registry as the single source of truth. This keeps cross-repository routing and authentication (including github-token) consistent across handlers. Sourced from PR #35901 (fix: safe output handlers now respect target-repo config) and the related single-source-safe-outputs-config / fix-safe-output-cross-repo-auth changesets. Added allowed-repos to the Cross-Repository YAML example.

Scan methodology and findings

Tone scan

Scanned all 64 scratchpad/*.md source files (plus the agents/ subdirectory) for the marketing/subjective vocabulary targeted by prior runs: powerful, seamless, leverage, comprehensive, extensive, enhanced, deep, robust, intuitive, effortless, first-class, out-of-the-box, battle-tested, production-ready, magic, easy/easily, simple/simply, and related intensifiers.

• Strong marketing terms (powerful, seamless, world-class, etc.): 0 violations in source files — all matches were either dev.md changelog quotes of past fixes or literal identifiers (unlock command/script names).
• gracefully (e.g. "handles errors gracefully", "gracefully degrades"): retained — standard engineering vocabulary, never flagged by prior runs.
• enhanced: most matches are code identifiers (EnhanceError), proposal section headings, or before/after config deltas with a stated baseline — left as descriptive language.
• deep: most matches are technical (nesting depth, "deep debugging") — only the engine-review-summary.md H1 was a genuine leftover.

Two confirmed fixes

The two changes above are the only confirmed subjective-intensifier issues. The engine-review-summary.md H1 fix resolves an inconsistency left by the v9.13 run, which corrected the same word in the file body but missed the title.

Coverage

• Spec files scanned: 64 (no new spec files since v9.14).
• dev.md Related Documentation link for engine-review-summary.md already omits the adjective, so the H1 rename introduces no link mismatch.

Historical comparison

Run	Date	Tone fixes	Notes
v9.15	2026-05-30	2	comprehensive/deep intensifiers; documented cross-repo handler consistency
v9.14	2026-05-22	10	"leverage" corporate-speak sweep
v9.13	2026-05-21	8	"deep" intensifiers
v9.12	2026-05-20	7	"enhanced/extensive"
v9.11	2026-05-19	3	"nice-to-have", "deep dive"

Trend: issue counts are declining as the corpus stabilizes; recent runs increasingly find leftovers from earlier partial fixes rather than fresh marketing language.

Next Steps

• Review the consolidated file at scratchpad/dev.md (v9.15).
• Confirm the cross-repository handler note matches current behavior.
• Verify the two tone replacements preserve the intended meaning.

A pull request with these changes has been opened from branch docs/consolidate-dev-instructions-20260530.

Generated by 📝 Developer Documentation Consolidator · opus48 3.3M · ◷

• expires on Jun 2, 2026, 2:10 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-02T14:10:30.344Z.

Closed by Workflow