Spec template: name each source file with line ranges, not whole packages
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
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Similar issues
-
cognition facet:consolidation memory ready size:S
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
Judgment-Pack/judgment-pack-spec#335 ·
Maintainers usually reply within 1 day
-
docs pydanty:is-working
Difficulty 1/5 Under an hour Newbie friendliness 88/100
pydantic/pydantic-ai#13563 ·
Maintainers usually reply within 1 day