Skills write headers by the canon's part boundaries, and warn about tabs

Open
  • Is something wrong?
#124 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
markdown
Domain
devtools, documentation

Research direction

Start with the canon block in docs/reference/authoring-formats.md (section Indentation, Where a part starts and ends) and its copy in living-doc-shared/references/living-doc-bdd-schemas.md, then read the header-writing SKILL.md files under agentic/.claude/skills/ (create-user-story, create-feature, create-functionality, update, gherkin-living-doc-sync, pageobject-scan). Done when each skill links the canon block instead of restating it, cross-reference notes go under the header's notes: key, and no skill writes a tab or no-break space into a header, with an eval per item per agentic/docs/testing/eval-protocol.md. The issue's grep re-check should find a tab rule.

Written by the indexing model from the issue text.

Description

type:tech-debt
Description of Technical Debt

The canon says where each part of a header starts and ends, what makes a header present, and that every line the
reader does not take is reported (docs/reference/authoring-formats.md § Indentation, Where a part starts and
ends). living-doc-utilities reads headers by exactly these rules, and the canon copy in
living-doc-shared/references/living-doc-bdd-schemas.md carries the block. The skills that write or update headers
do not yet follow it:

  • Header lines. living-doc-create-user-story, -create-feature, -create-functionality, living-doc-update and
    gherkin-living-doc-sync follow the template's levels. Nothing says that a single-value key takes one line, that
    every header line carries its marker, that all AC: lines sit at one level, or that the title carries the id.
  • Cross-reference notes. living-doc-pageobject-scan and living-doc-update write no notes: on a
    cross-reference header, which the canon now allows for notes about that page.
  • Tabs. No skill checks for a tab or a no-break space in a header's indentation. The reader takes a tab as one
    space in a header, so #, a tab and two spaces before status: Deprecated reads as the key status while an editor
    shows wrapped text, and the story silently turns deprecated.
Impact of Technical Debt
  • A header a skill writes may be read differently from what the author sees.
  • A tab in an existing header silently changes an entity.
Category

Code Quality / Refactoring

Priority

Medium - Should be addressed soon

Proposed Solution
  1. Each header-writing skill links the canon block (never restates it), and its output holds: the title carrying the
    id, every header line with its marker, every key at the key level, every AC: line at one indent, a single-value
    key on one line, keys in the template's order with acceptance_criteria: last.
  2. living-doc-pageobject-scan and living-doc-update write a cross-reference page's notes under that header's
    notes:, never into the full header's.
  3. No skill writes a tab into a header. A skill reading an existing header reports each tab or no-break space in an
    indent (file, line, how the reader takes it) and replaces it only on the user's confirmation. normalize(...).changes
    already lists one whitespace change per rewritten indent.

An eval for each of the three, by agentic/docs/testing/eval-protocol.md.

Effort Estimate

3-5 days

Dependencies / Related

The "Check authored living-doc input before merge and while typing" issue (running the reader over a draft is out of scope here).

Additional Context

Measured 2026-11-12 at living-doc 2df73dc. Re-check:

grep -n -i "no-break space\|tab" agentic/.claude/skills/*/SKILL.md finds no tab rule while this is open.

Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 14m
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.