Internal developer documentation for the RSS Dashboard plugin.
- Architecture Guardrails
- Compliance Patterns and Audit Guardrails
- Feed Data Lifecycle
- Feed Validation
- Fixture Vault for Manual Testing
- Issue Labels and Milestones
- Obsidian Settings Reference
- Release Notes Workflow
- Starred State and Tags
- Test Feeds for Manual QA
- Testing Guide
- Pull Request Template
This section is the source of truth for implementation-plan organization.
docs/
plans/ # Active and future work
archive/
README.md # Searchable archive catalog
plans/
unreleased/ # Implemented and validated, not released
v<version>/ # Shipped plans grouped by first release
unshipped/ # Deferred, rejected, or superseded plans
investigations/
<YYYY>/ # Incident, bug, and research records
adr/
NNNN-<slug>.md # Durable architectural decisions
Use release versions as the primary grouping for implemented feature and bug
plans. Use calendar years for investigations whose value is chronological.
Keep durable architectural decisions in docs/adr/; update their status
to superseded and link the replacement instead of archiving them.
Use this frontmatter for new active plans:
---
status: idea
created: YYYY-MM-DD
issue: ""
milestone: ""
owner: unassigned
workstream: ""
sequence: null
depends_on: []
release_requirement: ""
implementation: ""
---- Use
ideawhile exploring,proposedwhile design is under review,acceptedwhen approved for implementation,blockedwhen an accepted plan has an unmet dependency, andin-progressafter implementation begins. - Keep
issueempty until a canonical GitHub issue exists. Before implementation or milestone assignment, create the issue and store its exact URL. - Keep
milestoneempty until the issue joins a release milestone. Userelease_requirement: requiredorstretchonly for milestone work. - Use
workstream,sequence, anddepends_ononly when they add real coordination value. Before issue creation, dependencies may be draft plan filenames. After issue creation, replace them with canonical issue URLs. - An owner may remain
unassigned; issue identity and assignment are separate.
Before archiving an implemented plan, replace its lifecycle fields with:
---
status: implemented
completed: YYYY-MM-DD
released_in: unreleased
issue: ""
implementation: ""
---- Set
released_intounreleaseduntil release cut, then replace it with the version number. - Preserve an exact canonical issue URL when one exists.
- Put a PR URL or commit hash in
implementationwhen known; leave it empty rather than inventing one. - For deferred, rejected, or superseded plans, use that value for
status, move the file todocs/archive/plans/unshipped/, and addsuperseded_bywhen applicable.
Use lowercase kebab-case and a two-stage identity:
- Before a canonical issue exists, use
draft-YYYYMMDD-<descriptive-slug>.md. - After creating the issue, rename the plan once to
<issue-number>-<descriptive-slug>.mdand keep that filename through implementation and archival.
Examples:
draft-20260816-refresh-status-indicators.md
143-refresh-status-indicators.md
The date identifies a draft; it is not a promised delivery date. Use product or domain language that is understandable without a private abbreviation list. Keep status, priority, ownership, milestone, and release version in frontmatter or GitHub rather than filenames.
Release roadmaps are durable coordination artifacts and use
release-v<version>-roadmap.md, or release-vnext-roadmap.md before the version
is chosen. ADRs retain NNNN-<slug>.md under docs/adr/.
Legacy plans do not need opportunistic renaming. Normalize them through a dedicated documentation migration so every inbound link is updated together.
- Capture an uncommitted idea in a GitHub Discussion or a dated draft plan.
- Triage it as accepted, deferred, rejected, superseded, or still proposed.
- For accepted work, create a GitHub issue, rename the plan with the issue number, and replace draft dependencies with issue URLs. Label it as described in Issue Labels and Milestones.
- Keep accepted backlog issues unassigned, in the
vNextmilestone until they're scheduled for a release. - Add only intended release work to the release milestone; mark it Required or Stretch in the Project and plan metadata.
- Use an issue branch and pull request that link the canonical issue. Update the plan when implementation changes the accepted contract.
- Complete validation, changelog, archive, release-note, and milestone gates through the completion workflow below.
- Keep the plan in
docs/plans/while behavior is incomplete or validation is failing. - Update the plan when implementation changes its accepted design, file map, tests, limitations, or manual verification.
- After implementation and every required validation gate succeed, mark the
plan
implementedand move it todocs/archive/plans/unreleased/unless a release version is already assigned. - Update all repository links to the moved file.
- Add or update its row in
docs/archive/README.md, including status, completion date, release, and implementation link when available. - Keep the granular user-facing change in
CHANGELOG.md; the archived plan is supporting developer history, not public release-note copy.
At release cut, move implemented plans from unreleased/ into
docs/archive/plans/v<version>/, replace released_in, update the archive
catalog and repository links, and include the user-facing summary under
docs/releases/<version>.md.