Reformat roadmap - #210
Merged
Merged
Conversation
Rewrite the roadmap to follow the documentation style guide for phases, steps, and dotted task numbering. Preserve all existing roadmap tasks while regrouping work into balanced steps, splitting overburdened sections, and removing single-task steps. Add explicit per-task citations to relevant design documents and parser specifications, and annotate cross-step dependencies with dotted task references where needed.
Contributor
Summary by CodeRabbit
WalkthroughSummarise changes: add Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
Contributor
Reviewer's GuideReformats the project roadmap into a structured, numbered task hierarchy with cross-references to design docs, and extends the documentation style guide with roadmap conventions and ADR standards, plus some minor wording and punctuation updates. Entity relationship diagram for numbered roadmap structureerDiagram
PHASE {
int id
string title
string description
bool complete
}
STEP {
int id
int phase_id
string title
string description
bool complete
}
TASK {
int id
int step_id
string title
string description
bool complete
string dotted_number
string success_criteria
}
DESIGN_DOC_SECTION {
string path
string section_reference
}
DEPENDENCY {
int from_task_id
int to_task_id
string dotted_reference
}
PHASE ||--o{ STEP : contains
STEP ||--o{ TASK : contains
TASK }o--o{ DESIGN_DOC_SECTION : cites
TASK ||--o{ DEPENDENCY : depends_on
Flow diagram for ADR authoring and lifecycleflowchart TD
A["Author identifies significant architectural decision"] --> B["Create new ADR file adr_NNN_short_description in docs directory"]
B --> C["Fill mandatory sections: Status, Date, Context_and_problem_statement"]
C --> D["Add conditional sections: Decision_drivers, Options_considered, Decision_outcome, Risks, etc."]
D --> E["Review ADR with team and update Status to Accepted or keep as Proposed"]
E --> F["If superseded, create new ADR and mark original as Superseded"]
F --> G["Reference ADR from roadmap tasks and design documents"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- In the ADR template, consider replacing the hard-coded
Proposed.status with a placeholder (e.g.<Proposed | Accepted | Superseded | Deprecated>) so authors are nudged to choose the correct value instead of copy-pastingProposed. - The ADR guidance section refers to Decision Drivers in the narrative but the template heading is
## Decision Driverswhile the earlier list of "Required/Conditional sections" uses slightly different casing; aligning names and casing across those lists and the template will make the prescribed structure easier to follow.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the ADR template, consider replacing the hard-coded `Proposed.` status with a placeholder (e.g. `<Proposed | Accepted | Superseded | Deprecated>`) so authors are nudged to choose the correct value instead of copy-pasting `Proposed`.
- The ADR guidance section refers to **Decision Drivers** in the narrative but the template heading is `## Decision Drivers` while the earlier list of "Required/Conditional sections" uses slightly different casing; aligning names and casing across those lists and the template will make the prescribed structure easier to follow.
## Individual Comments
### Comment 1
<location> `docs/documentation-style-guide.md:173-174` </location>
<code_context>
+ - Phases: 1, 2, 3, …
+ - Steps: 1.1, 1.2, 1.3, …
+ - Headline tasks: 1.1.1, 1.1.2, 1.1.3, …
+- **Checkboxes:** Precede task and sub-task items with a GitHub-Flavoured
+ Markdown (GFM) checkbox (`[ ]`) to track completion status.
+- **Dependencies:** Note non-linear dependencies explicitly. Where a task
</code_context>
<issue_to_address>
**suggestion (typo):** Use the official product name “GitHub Flavored Markdown (GFM)”
Please update this reference to the official name: “GitHub Flavored Markdown (GFM)” (no hyphen, US spelling of “Flavored”), even if the rest of the guide uses British English.
```suggestion
- **Checkboxes:** Precede task and sub-task items with a GitHub Flavored
Markdown (GFM) checkbox (`[ ]`) to track completion status.
```
</issue_to_address>
### Comment 2
<location> `docs/documentation-style-guide.md:305` </location>
<code_context>
+
+## Decision outcome / proposed direction
+
+<State the chosen or recommended approach and summarise the rationale.>
+
+## Known risks and limitations
</code_context>
<issue_to_address>
**suggestion (review_instructions):** “summarise” uses an -ise ending; en-GB-oxendict prefers the -ize form here.
To follow the en-GB-oxendict guidance specified earlier in this document, change “summarise” to “summarize” in this sentence.
<details>
<summary>Review instructions:</summary>
**Path patterns:** `**/*.md`
**Instructions:**
Use en-GB-oxendic (-ize / -yse / -our) spelling and grammar.
</details>
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/documentation-style-guide.md`:
- Around line 200-202: Replace the first occurrence of the acronym "RBAC" with
its expanded form by updating the checklist entry "1.2.1. Implement role-based
access control. Requires 1.1.1." so it reads "Implement role-based access
control (RBAC)" and ensure any subsequent uses remain as "RBAC"; target the
checklist item labeled "1.2.1." and the acronym "RBAC" in the surrounding items
(e.g., the bullet "Add RBAC middleware to API endpoints.") to keep the first-use
expansion consistent.
Apply all current PR review comment requirements to the roadmap and ADR guidance sections. Update product naming to "GitHub Flavored Markdown (GFM)", expand role-based access control (RBAC) on first use in the roadmap example, and correct the "summarize" spelling. Normalize ADR template section heading casing and replace the hard-coded status value with a status placeholder so authors must choose the correct state.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/documentation-style-guide.md (1)
140-152:⚠️ Potential issue | 🟡 MinorWrap bullets and paragraphs at 80 columns.
Reflow the long bullet lines and ADR naming line to comply with the 80‑column limit for Markdown prose.
Proposed diff
-- Define outcomes, not intentions: Phrase tasks in terms of the capability - delivered (e.g. “Implement role-based access control for API endpoints”), not - aspirations like “Improve security”. +- Define outcomes, not intentions: Phrase tasks in terms of the capability + delivered (e.g. “Implement role-based access control for API endpoints”), + not aspirations like “Improve security”. -- Quantify completion criteria: Attach measurable finish lines (e.g. “90% - test coverage for new modules”, “response times under 200ms”, “all endpoints - migrated”). +- Quantify completion criteria: Attach measurable finish lines (e.g. “90% + test coverage for new modules”, “response times under 200ms”, “all + endpoints migrated”). -- Tie to dependencies and sequencing: Document prerequisites, so tasks can be - scheduled realistically (e.g. “Introduce central logging service” before “Add - error dashboards”). +- Tie to dependencies and sequencing: Document prerequisites, so tasks can be + scheduled realistically (e.g. “Introduce central logging service” before + “Add error dashboards”). -- Bound scope explicitly: Note both in-scope and out-of-scope elements (e.g. - “Build analytics dashboard (excluding churn prediction)”). +- Bound scope explicitly: Note both in-scope and out-of-scope elements (e.g. + “Build analytics dashboard (excluding churn prediction)”). -Name ADR files using the pattern `adr-NNN-short-description.md`, where `NNN` is +Name ADR files using the pattern `adr-NNN-short-description.md`, where `NNN` +isAlso applies to: 214-214
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/documentation-style-guide.md` around lines 140 - 152, Reflow the long Markdown bullets and the ADR naming line so no line exceeds 80 characters: edit the listed bullets ("Define outcomes, not intentions:", "Quantify completion criteria:", "Break into atomic increments:", "Tie to dependencies and sequencing:", "Bound scope explicitly:") and the ADR naming line to wrap prose at 80 columns while preserving wording and Markdown list structure; ensure wrapped lines maintain sentence integrity (prefer breaking at clause boundaries) and keep the same bullet markers and punctuation.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/documentation-style-guide.md`:
- Line 206: Change the heading "Architectural Decision Records (ADRs)" to
sentence case by rewriting it as "Architectural decision records (ADRs)" so it
conforms to the documentation-style rules; locate the heading text and replace
it with the new sentence-case heading exactly as shown.
---
Outside diff comments:
In `@docs/documentation-style-guide.md`:
- Around line 140-152: Reflow the long Markdown bullets and the ADR naming line
so no line exceeds 80 characters: edit the listed bullets ("Define outcomes, not
intentions:", "Quantify completion criteria:", "Break into atomic increments:",
"Tie to dependencies and sequencing:", "Bound scope explicitly:") and the ADR
naming line to wrap prose at 80 columns while preserving wording and Markdown
list structure; ensure wrapped lines maintain sentence integrity (prefer
breaking at clause boundaries) and keep the same bullet markers and punctuation.
Update the documentation style guide heading to comply with the sentence-case rule. Change "Architectural Decision Records (ADRs)" to "Architectural decision records (ADRs)" exactly as requested.
Replace "df12 software" with "software by df12 Productions" in the documentation style guide introduction to match the requested project wording.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/documentation-style-guide.md`:
- Around line 254-264: The three consecutive bullet lines under the "Formatting
guidance" heading all start with "Use", which triggers the style warning; edit
the bullets (e.g., the items that begin "Use second-level headings", "Use
third-level headings", and "Use tables to compare options") to vary sentence
structure—rewrite one or two to start with a phrase like "Prefer", "Adopt", or
reframe as an instruction starting with the object (e.g., "Second-level headings
(`##`) should be used for major sections")—keeping the same guidance and
examples (heading markers, table caption suggestion, code snippet advice) but
changing sentence openings to avoid repetition.
Address PR feedback about repeated sentence starts in the ADR formatting guidance section. Vary sentence openings across consecutive bullets while preserving the same guidance and meaning.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/documentation-style-guide.md`:
- Around line 305-307: In the ADR template header "## Decision outcome /
proposed direction" update the placeholder text that currently reads "<State the
chosen or recommended approach and summarise the rationale.>" to use American
-ize spelling by replacing "summarise" with "summarize"; ensure only that token
is changed (keep surrounding punctuation and capitalization identical) so the
template now reads "<State the chosen or recommended approach and summarize the
rationale.>".
---
Duplicate comments:
In `@docs/documentation-style-guide.md`:
- Around line 255-263: The three bullets under the "Formatting guidance" heading
repeat the word "Use" and should be reworded for variety and flow: edit the
bullets beneath the "Formatting guidance" section so each starts differently
(e.g., "Prefer", "Apply", "Present", "Include") while preserving the same rules
and examples (second-level headings, third-level headings, tables with captions,
code snippets with language identifiers and no_run for Rust); update the four
existing bullet lines (the ones referencing headings, subsections, tables, and
code snippets) to distinct verbs/phrases so the guidance reads less repetitive
and keeps the original guidance intact.
Contributor
There was a problem hiding this comment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/documentation-style-guide.md`:
- Around line 257-259: Reword the three consecutive bullet items that begin
"Use" (the lines "Use second-level headings (`##`) for major sections.", "Use
third-level headings (`###`) for subsections (e.g. phases, option names).", and
"Use tables to compare options when multiple dimensions are relevant. Include")
to vary sentence openings while preserving the guidance and examples; e.g.,
change one to "Second-level headings (`##`) should be used for major sections.",
another to "Format subsections with third-level headings (`###`) (e.g. phases,
option names).", and the third to "When multiple dimensions are relevant,
compare options using tables and include…" so the meaning and examples remain
identical but the repeated "Use" start is removed.
leynos
added a commit
that referenced
this pull request
Feb 18, 2026
* Update documentation style guide * Ignore grepai index * Restructure roadmap into phased task hierarchy Rewrite the roadmap to follow the documentation style guide for phases, steps, and dotted task numbering. Preserve all existing roadmap tasks while regrouping work into balanced steps, splitting overburdened sections, and removing single-task steps. Add explicit per-task citations to relevant design documents and parser specifications, and annotate cross-step dependencies with dotted task references where needed. * Align style guide with PR review feedback Apply all current PR review comment requirements to the roadmap and ADR guidance sections. Update product naming to "GitHub Flavored Markdown (GFM)", expand role-based access control (RBAC) on first use in the roadmap example, and correct the "summarize" spelling. Normalize ADR template section heading casing and replace the hard-coded status value with a status placeholder so authors must choose the correct state. * Use sentence case for ADR heading Update the documentation style guide heading to comply with the sentence-case rule. Change "Architectural Decision Records (ADRs)" to "Architectural decision records (ADRs)" exactly as requested. * Use preferred df12 wording in style guide Replace "df12 software" with "software by df12 Productions" in the documentation style guide introduction to match the requested project wording. * Improve ADR formatting guidance readability Address PR feedback about repeated sentence starts in the ADR formatting guidance section. Vary sentence openings across consecutive bullets while preserving the same guidance and meaning. * Additional documentation style guide improvements * Fix missing -ize
This was referenced Jul 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by Sourcery
Reformat and expand project documentation around the roadmap and documentation standards without changing code or behaviour.
Documentation:
Chores: