Skip to content

fix: decisions-framework - Resolve Markdown linting errors #1511

Open

Description

@ashleyshaw

Overview

Fix markdown linting errors in the decisions framework document. The document contains complex anchor link references that don't comply with markdown standards.

File

projects/active/repo-restructuring-2026-07-25/DECISIONS_FRAMEWORK-50-QUESTIONS.md

Issues Found (309 total)

Error Categories

  1. MD051: Link fragments (200+ instances)

    • Problem: Special characters in link targets not properly escaped
    • Example: [#1.-organizational-&-access-patterns] has unescaped & and .
    • Markdown requires escaping: [#1\.-organizational-\&-access-patterns]
  2. MD029: Ordered list prefix (20+ instances)

    • Problem: List numbering doesn't follow sequential pattern
    • Example: List shows 1, 2, 4, 5 instead of 1, 2, 3, 4
  3. MD012: Multiple blank lines (40+ instances)

    • Problem: More than one consecutive blank line found
    • Should be at most 1 blank line between sections
  4. MD009: Trailing spaces (49+ instances)

    • Problem: Lines end with unnecessary whitespace

Solution Options

Option A: Fix all formatting issues

  • Escape special characters in link fragments
  • Correct list numbering
  • Remove trailing spaces
  • Remove excess blank lines

Option B: Add linting exceptions

If this document intentionally uses complex link formatting, add to .markdownlintrc.json:

{
  "overrides": [
    {
      "files": ["projects/active/repo-restructuring-2026-07-25/DECISIONS_FRAMEWORK-50-QUESTIONS.md"],
      "MD051": false,
      "MD029": false
    }
  ]
}

Validation

After fixes: npm run lint:md should show 0 errors for this file.

Priority

Medium — Moderate effort, affects CI/CD validation pipeline

Parent Epic

Part of #1507: Pre-existing validation errors cleanup


Definition of Ready (DoR)

  • Reproduction steps clearly documented
  • Expected vs actual behavior defined
  • Environment/version information captured
  • Related issues/PRs linked
  • Severity/impact assessed
  • Acceptance criteria for fix defined

Definition of Done (DoD)

  • Bug fix verified and reproduction steps no longer apply
  • Root cause identified and documented
  • Tests added/updated to prevent regression; CI green
  • No new warnings or errors introduced
  • Docs/changelog updated
  • Backport considered (if applicable)
  • Release notes prepared

Activity

  1. linear-code commented on Aug 4, 2026

    @linear-code
  2. github-actions commented on Aug 4, 2026

    @github-actions
    Contributor

    ✅ Template check passed after update. Thanks for fixing the issue body.

  3. github-actions commented on Aug 4, 2026

    @github-actions
    Contributor

    ⏱️ Aging and SLA annotation

    • Age: 4 day(s)
    • SLA state: Within SLA
    • Thresholds: warn at 7 days, breach at 14 days
    • Last updated: 2026-08-09T11:41:30.747Z

    Maintained by project-meta-sync workflow.

  4. added theissue type on Aug 4, 2026
  5. added this to the v1.0 milestone on Aug 4, 2026
  6. self-assigned this
    on Aug 7, 2026
  7. modified the milestones: v1.0, v1.1 on Aug 29, 2026
  8. changed the title [-]docs: fix markdown linting errors in DECISIONS_FRAMEWORK document[/-] [+]fix: decisions-framework - Resolve Markdown linting errors[/+] on Sep 8, 2026
  9. github-actions commented on Sep 8, 2026

    @github-actions
    Contributor

    ⚠️ Bare Labels Detected

    This issue has labels that are not in the canonical taxonomy:

    • migrate:priority:normal
    • migrate:status:ready
    • migrate:type:bug
    • migrate:area:documentation

    Valid Canonical Labels

    Please use labels with a prefix from the canonical taxonomy:

    • Type: type:bug, type:feature, type:task, type:documentation, etc.
    • Status: status:needs-triage, status:in-progress, status:done, etc.
    • Priority: priority:critical, priority:high, priority:normal, priority:low
    • Area: area:ci, area:docs, area:labels, area:security, etc.
    • Meta: meta:needs-changelog, meta:duplicate, meta:blocked, etc.

    For the complete list, see .github/labels.yml.

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

Metadata

Metadata

Assignees

Type

Fields

Priority

None yet

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions