[docs] Consolidate developer specifications into instructions file (v9.5)#31348
Merged
pelikhan merged 1 commit intoMay 10, 2026
Merged
Conversation
Maintenance tone scan across 63 spec files.
Fixed 2 tone issues:
- actions.md: vague "Cannot easily share" → specific "No mechanism for sharing"
- gastown.md: marketing prose ("full-featured agentic workflow platform",
"security-first approach") → factual "extend gh-aw to support",
"preserving its existing security model"
No new spec files since v9.4.
github-actions
Bot
added
automation
documentation
pelikhan
deleted the
docs/dev-instructions-consolidation-2026-05-10-02afe8b127813a1b
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Developer Documentation Consolidation
Daily maintenance pass on the consolidated developer instructions in
scratchpad/dev.md. Covers 63 spec files inscratchpad/. No new spec files since v9.4.Changes Made
Tone fixes (2 issues across 2 files)
scratchpad/actions.md(line 35)Cannot easily share actions across repositoriesNo mechanism for sharing actions across repositoriesscratchpad/gastown.md(line 958)These enhancements would position gh-aw as a full-featured agentic workflow platform capable of both basic automation and complex multi-agent coordination, while maintaining its security-first approach and GitHub-native integration.These enhancements would extend gh-aw to support both basic automation and multi-agent coordination, while preserving its existing security model and GitHub-native integration.Rationale:
actions.md: "easily" was a vague qualifier in a problem-statement bullet; replaced with a concrete description of the gap.gastown.md: "full-featured agentic workflow platform" and "security-first approach" are marketing-toned in running prose. Replaced with neutral, factual framing consistent with prior tone scans (v8.4 "battle-tested" → "established", v8.2 "Developer-friendly" → "Non-critical diagnostic").Document history
scratchpad/dev.mdversion: 9.4 → 9.5Last Updated: 2026-05-09 → 2026-05-10Files Modified
scratchpad/dev.md— version bump and history entryscratchpad/actions.md— 1 tone fixscratchpad/gastown.md— 1 tone fixValidation
Scan coverage
powerful,seamless,robust,cutting-edge, etc.), vague qualifiers (easily,simply,just), enthusiasm words (amazing,awesome,delightful), and design-priority labels (first-class,security-first)security-first/safety-firstoccurrences appear in labeled bullets or quoted comparisons (e.g.mdflow-comparison.md:567,oh-my-code.md:96) where they describe a model name rather than promoting it; left in place to avoid changing labels.