Skip to content

[WIP] Improve readability of rules by moving meta info - #177

Merged
jeduden merged 3 commits into
mainfrom
claude/improve-readability-of-rules
Apr 26, 2026
Merged

[WIP] Improve readability of rules by moving meta info#177
jeduden merged 3 commits into
mainfrom
claude/improve-readability-of-rules

Conversation

@Claude

@Claude Claude AI commented Apr 26, 2026

Copy link
Copy Markdown
Contributor

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.


This section details on the original issue you should resolve

<issue_title>Improve readabliity of rules</issue_title>
<issue_description>Move rendered front matter meta info to the end of the rule.

New proposed proto for rules:

---
id: '=~"^MDS[0-9]{3}$"'
name: 'string & != ""'
status: '"ready" | "not-ready"'
description: 'string & != ""'
fixable: 'yes':'no'
implementation:  'string & != ""'
category: 'string & != ""'
archetype: 'string'
---
# {id}: {name}

<!-- Rule README template. Copy this file, replace placeholders,
     delete sections and comments that don't apply.
     Front matter is required. The catalog directive reads
     id, name, status, description to generate the rules table.
     Repeat the description verbatim. Use prescriptive voice,
     present tense: "Headings must ..." not "Checks that ...". -->

{description}

<!-- Bullets in this order: ID, Name, Status, Default, Fixable,
     Implementation, Category, Archetype (if applicable).
     Default may include key settings: "enabled, max: 80".
     Categories: code, heading, line, link, list, meta,
     whitespace. Delete Archetype bullet if not used. -->

<!-- Optional: ## Settings
     Include only when rule implements Configurable.
     Type: int, string, list. Description: fragment,
     no period. Delete if not applicable. -->

## ...

<?allow-empty-section?>

## Config

<!-- Show enable, disable, and (if configurable) custom
     settings as separate labeled yaml blocks. -->

```yaml
rules:
  rule-name: true
```

Disable:

```yaml
rules:
  rule-name: false
```

## ...

<?allow-empty-section?>

## Examples

<!-- Use <?include?> directives referencing fixture files
     in the rule's good/ and bad/ directories (or good.md
     and bad.md files). Use wrap: markdown so the fixture
     renders inside a fenced code block.
     Add ### Good and ### Bad subsections.
     Complex rules: multiple subsections labeled
     "### Good -- description" or "### Bad -- description".
     Always use include directives for examples. When the
     included output cannot show the difference (e.g., EOF
     newline in MDS009), add explanatory prose after the
     include. -->

<!-- Optional: ## Diagnostics
     Include when the rule emits more than one distinct
     message. Delete for single-message rules. -->

<!-- Optional: ## Edge Cases
     Include for complex rules. Delete otherwise. -->

## ...

<?allow-empty-section?>

## Meta-Information

- **ID**: {id}
- **Name**: `{name}`
- **Status**: {status}
- **Default**: enabled
- **Fixable**: no
- **Implementation**:
  [source](./)
- **Category**: CATEGORY
- **Archetype**:
  [NAME](../../../docs/design/archetypes/NAME/)
````</issue_description>

## Comments on the Issue (you are @claude[agent] in this section)

<comments>
</comments>

@Claude Claude AI assigned Claude and jeduden Apr 26, 2026
@Claude Claude AI linked an issue Apr 26, 2026 that may be closed by this pull request
@codecov

codecov Bot commented Apr 26, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.24%. Comparing base (4cefa66) to head (48044c1).
⚠️ Report is 27 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #177   +/-   ##
=======================================
  Coverage   93.24%   93.24%           
=======================================
  Files         113      113           
  Lines       12202    12202           
=======================================
  Hits        11378    11378           
  Misses        498      498           
  Partials      326      326           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Updated all 38 rule README files to move meta-information bullets from after description to a new "Meta-Information" section at the end
- Updated internal/rules/proto.md schema to reflect new structure
- All mdsmith checks pass
- All tests pass

Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/6b403bfb-b3f1-4f0e-94e4-5a49f18cc48e

Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
@Claude
Claude AI requested a review from jeduden April 26, 2026 17:49
@jeduden
jeduden marked this pull request as ready for review April 26, 2026 18:28
Copilot AI review requested due to automatic review settings April 26, 2026 18:28

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Moves the per-rule rendered meta-information block (ID, status, default, etc.) to the end of each rule README to improve scan-ability and keep the descriptive content up front, aligning with the rule README proto template used by required-structure.

Changes:

  • Updated internal/rules/proto.md to place the meta-information section at the end of the template.
  • Reordered content in rule READMEs (MDS001–MDS038) to move the existing meta-information bullets into a final ## Meta-Information section.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
internal/rules/proto.md Moves the template meta-information block to the end and introduces a ## Meta-Information section.
internal/rules/MDS001-line-length/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS002-heading-style/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS003-heading-increment/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS004-first-line-heading/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS005-no-duplicate-headings/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS006-no-trailing-spaces/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS007-no-hard-tabs/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS008-no-multiple-blanks/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS009-single-trailing-newline/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS010-fenced-code-style/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS011-fenced-code-language/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS012-no-bare-urls/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS013-blank-line-around-headings/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS014-blank-line-around-lists/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS015-blank-line-around-fenced-code/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS016-list-indent/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS017-no-trailing-punctuation-in-heading/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS018-no-emphasis-as-heading/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS019-catalog/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS020-required-structure/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS021-include/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS022-max-file-length/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS023-paragraph-readability/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS024-paragraph-structure/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS025-table-format/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS026-table-readability/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS027-cross-file-reference-integrity/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS028-token-budget/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS029-conciseness-scoring/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS030-empty-section-body/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS031-unclosed-code-block/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS032-no-empty-alt-text/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS033-directory-structure/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS034-markdown-flavor/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS035-toc-directive/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS036-max-section-length/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS037-duplicated-content/README.md Moves meta-information block to the end under ## Meta-Information.
internal/rules/MDS038-toc/README.md Moves meta-information block to the end under ## Meta-Information.

Comment thread internal/rules/MDS020-required-structure/README.md Outdated
Move the [source](./) link to its own indented line to match
the format used in all other rule READMEs and the proto template.

Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/b0b4d651-f744-4490-85bf-53e588a6ad87

Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
@jeduden jeduden added queue Add to a PR to enqueue it queue:active Applied automatically when a PR is in an active batch and removed queue Add to a PR to enqueue it labels Apr 26, 2026
@jeduden

jeduden commented Apr 26, 2026

Copy link
Copy Markdown
Owner

🟢 Merge Queue — picked up

This PR is in the queue and will be batched with other queue-labelled PRs.

Next: No action needed — you'll get another comment when CI starts on the batch. View merge queue run.

@jeduden

jeduden commented Apr 26, 2026

Copy link
Copy Markdown
Owner

🔵 Merge Queue — CI running

Merged into batch branch merge-queue/batch-177-1777233286. View CI run.

Next: No action needed — you'll be notified when CI completes.

@jeduden jeduden removed the queue:active Applied automatically when a PR is in an active batch label Apr 26, 2026
@jeduden
jeduden merged commit a9364c0 into main Apr 26, 2026
13 checks passed
@jeduden

jeduden commented Apr 26, 2026

Copy link
Copy Markdown
Owner

Merge Queue — merged

This PR landed on main via commit a9364c0. CI run that validated the merge.

Next: Done — nothing more to do here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve readabliity of rules

3 participants