Skip to content

Document the reference page-citation convention in AGENTS.md #10008

Closed

Description

@hua7450

Problem

The reference-title convention used in the LIHEAP state PRs is not written down in this repository. In the round 3 review of PR #9743 (#9743 (comment)), the reviewer noted that neither main nor the branch has the rule in AGENTS.md, and that the model-development guidance keeps page numbers in href and out of the title. The rule lives in the author's local workspace instructions, which reviewers cannot see, so each PR reopens the same discussion.

Current state

  • AGENTS.md covers test cost and partner contract tests only.
  • CLAUDE.md says to cite specific regulation sections in variable reference and documentation, but says nothing about PDF pages or titles.
  • The model-development skill example in policyengine-skills (references/parameters.md) says "no page number in title" and puts #page=XX on the href.
  • No code-health test checks titles. tests/code_health/test_reference_urls.py checks URL shape only.

Convention to document

  1. One reference entry per source document. URLs that differ only by #page= point at the same source.
  2. One cited page: put it in the URL fragment (#page=57) and keep the title free of page text.
  3. Several cited pages: the href opens the first cited page and the title ends with #page 72-75 for a consecutive run or #page 29,32-33,36,41 for a nonconsecutive list (runs inside a list compress). Quote YAML titles that contain #.
  4. The URL fragment is one valid destination. Never write #page=1,3,5.
  5. Do not split one multi-page table into one entry per page. When a distinct table or table section starts on a page the href does not open, for example a second region's benefit matrix or the continuation page that holds the larger household sizes, give that section its own entry with a section-named title, so every modeled value is reachable from some href. This refinement came out of the PR Add Oregon LIHEAP regular heating assistance #9743 round 3 discussion.
  6. Variable reference tuples follow the same rules. Tuple entries have no title, so a # PDF pages … comment above a multi-page href lists the pages in the same shape, and is dropped when the href cites one page.

Proposed change

Add a "Parameter and variable references" section with the rules above to AGENTS.md (or CLAUDE.md, whichever reviewers read), and update the model-development skill in policyengine-skills so the two agree.

Activity

  1. added a commit that references this issue on Oct 8, 2026
    ad5ff39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions