chore(skills): unwrap markdown prose; trim project-CLAUDE duplication#4
Merged
Conversation
These sources were hand-wrapped at ~80-100 columns (no formatter enforces it — the repo has none), which reads as ragged short lines in diffs and was never an intentional convention. Join soft-wrapped prose and list-item continuations into one line per paragraph; a genuine paragraph break stays a blank line. Tables, fenced code, headings, and frontmatter are byte-identical (verified). Covers every markdown file except the four SKILL.md being reworked in the naming-coherence PR (which carries their unwrap, to keep zero file overlap). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The template's operational-rules block duplicated discipline the skills already teach when invoked (TDD, verify-before-done, PR-title hygiene, the spec/plan/state lifecycle). A rule stated in both the template and a skill drifts — the state-dir move had to be edited in both places. Keep only what a skill reads from here (the commit convention) or can't enforce alone (the two git/GitHub safety rules); delete the rest and say why. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR performs markdown hygiene updates across the plugin docs/skills: unwrapping prose so each paragraph is a single line, and reducing duplicated operational-rules guidance in the project-CLAUDE.md template.
Changes:
- Unwrap hand-wrapped markdown prose across several
SKILL.mddocs and the rootREADME.md. - Simplify
templates/project-CLAUDE.md“Operational rules” to avoid duplicating rules already taught by skills. - Update the planning feature-state template formatting (but the YAML frontmatter needs to remain valid YAML).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| templates/project-CLAUDE.md | Unwraps prose and trims the Operational rules block to reduce duplication with skills. |
| skills/testing-a-feature/SKILL.md | Unwraps prose paragraphs and list items for cleaner diffs/formatting. |
| skills/planning-a-feature/templates/feature-state.md | Reflows template content; frontmatter was collapsed into one line (must remain valid YAML). |
| skills/opening-a-pull-request/SKILL.md | Unwraps prose and list formatting in the PR-opening workflow skill. |
| skills/developing-a-feature/SKILL.md | Unwraps prose in the multi-PR/single-PR orchestration workflow skill. |
| README.md | Unwraps prose paragraphs and list items in repository documentation. |
| CLAUDE.md | Unwraps prose and list formatting in contributor guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The prose reference to `<!-- -->` guidance tripped the unwrap's comment-skip, leaving the paragraph split across two physical lines. It renders as one paragraph (adjacent lines join), but it's an incomplete unwrap — join it. Same defect class the PR #3 review caught in writing-github-issues.
The prose reflow only treated frontmatter as verbatim when it starts at line 1. feature-state.md opens with an HTML comment block before its `---` frontmatter, so the reflow joined the YAML fields onto one line — invalid, unparseable frontmatter. Restore the multi-line block; keep the one valid list-item unwrap the reflow also made.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
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
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.
Description
Two related markdown-hygiene cleanups for the plugin sources. No skill behaviour changes.
Changes
project-CLAUDE.mdtemplate's operational-rules block: drop the rules the skills already teach when invoked (TDD, verify-before-done, PR-title hygiene, spec/plan/state lifecycle), keeping only the commit-convention the PR skill reads from CLAUDE.md and the two git/GitHub safety rules. A rule duplicated between the template and a skill drifts — the state-dir move had to be edited in both.Testing
The reflow was verified to leave tables, fenced code, headings, and YAML frontmatter byte-identical and to preserve heading counts and trailing newlines on every touched file. No executable code in this repo.