Skip to content

skills/design-issue: support and validate structured Revision History tables for multi-phase design document updates #885

Description

@JoshuaVSherman

Child of web-jam-tools#737 #737 ("design-issue skill enhancements and fixes").

What this builds

Updates skills/design-issue/SKILL.md and src/design-issue/lint_doc.ts to support and enforce a structured ## Revision History table when design documents are resumed and updated for major milestone iterations and epics.

  1. Updates skills/design-issue/SKILL.md to define the standing rule for ## Revision History:
    • When an existing design document undergoes a major update or new Phase Epic, it carries a structured markdown table with columns: | Date | Phase / Milestone | Epic Link | Summary of Key Additions & Enhancements |.
    • Distinguishes structured revision history tables from forbidden unstructured historical narrative prose ("an earlier version said", "what changed", "why this was withdrawn").
  2. Updates src/design-issue/lint_doc.ts:
    • Adjusts revisionNarrationRegexes so that the literal heading ## Revision History and compliant markdown table rows are permitted.
    • Validates that if a ## Revision History section is present, it adheres to the required table schema and non-empty summary cells.
  3. Adds automated unit test coverage in test/design_issue_lint_doc.test.ts.

Design reference

~/Dropbox/web-jam-llms/Token_Savings/design-issue-enhancements-design-2026-08-23.md

STOP and say so if this path cannot be read. Do not reconstruct the requirements from this issue body, from comments, or from guesswork.

Acceptance criteria

  1. skills/design-issue/SKILL.md documents the ## Revision History table schema and multi-phase resume requirements.
  2. deno task design:lint-doc passes cleanly on design documents carrying a compliant ## Revision History table.
  3. deno task design:lint-doc continues to fail design documents carrying forbidden unstructured narrative phrases.
  4. All unit tests in test/design_issue_lint_doc.test.ts pass 100% green.
  5. deno task fmt:check, deno task lint, and deno task sast pass 100% green.

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions