Spec template: name each source file with line ranges, not whole packages

Open Beginner friendly
#29 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown
Domain
documentation

Research direction

Open shared/dev-team/skills/orchestrate/references/spec-template.md and read the "Read" section, then the "Handoffs" section of the orchestrate skill mentioned in the proposal. Add the suggested <source file>:<start>-<end> line to the template and, if accepted, the handoff sentence. Done means the template asks for exact files and line ranges rather than whole packages, but the open points (pinned commits, fixture entry names) need the owner's decision first.

Written by the indexing model from the issue text.

Description

proposal

Proposal

In the spec template (shared/dev-team/skills/orchestrate/references/spec-template.md), make the "Read" section name each source file that the implementer must study with line ranges, not as a whole package or directory.

This is a proposal, not a decision. The owner accepts or closes it.

The problem

When a task ports code or reproduces the behavior of an existing implementation, the orchestrator usually reads the sources while it writes the design and the spec. The spec then often names the sources at package or directory level ("the X package, with its tests and fixtures"). Each implementer and reviewer reads most of that material again, cold. One observed case: writing the design documents for several related components took approximately 150 KB of source reads, and each of the later implementation specs would have sent an implementer through most of it again.

The orchestrator already knows which parts matter, because it read them. A package-level pointer throws that knowledge away.

The change

In the "Read" section of the template, add a line for source material, for example:

- <source file>:<start>-<end>: <what to take from it> (name the exact module, its tests
  and the fixture entries for this task, with line ranges; not the whole package)

Possibly also a sentence in the orchestrate skill, "Handoffs": when the orchestrator read sources for the design, it gives the implementer the exact files and line ranges it used.

Open points

  • Line ranges go stale if the source moves. A pinned commit of the source makes them stable. Should the template ask for the commit as well?
  • A fixture file with many entries (for example one golden file for several components) needs entry names or IDs, not only line ranges.
Dominant language
Python
Stars
0
Forks
0
Avg merge
38m
Merged PRs (30d)
26

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.