Skip to content
sdlc

T-U6ZX-setup-obsidian-backlog-dir-mismatch

Status: closed/superseded · Impact: medium · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem in rust-path-opener (2026-05-19-obsidian-vault-id-uri). Review and promote to open/ready before picking up.

Goal

Section titled “Goal”

/sdlc:setup --obsidian creates the plural entity directory docs/planning/backlogs/ (consistent with epics/, milestones/, tasks/) but then writes its Obsidian Bases file into docs/planning/backlog/backlog.base (singular). The result is two parallel directories — one with the entity files, one with the unattached Bases query — and the Bases query points at the wrong folder anyway. Make the singular-vs-plural naming consistent so the Bases file lands in the same directory as the entities it filters.

Today

Section titled “Today”
  • scripts/setup_planning.py discovers entity types from plugin/entities/<type>/schema.json. For backlog, the directory is created as docs/planning/backlogs/ (plural — matches the established convention in epics/milestones/tasks). Observed in dev repo: docs/planning/backlog/ AND docs/planning/backlogs/ both exist on main.
  • The --obsidian step copies plugin/entities/<type>/base.yaml to docs/planning/<plural>/<plural>.base. For backlog it instead writes to docs/planning/backlog/backlog.base (singular dir, singular filename). Verified in rust-path-opener (docs/planning/backlog/backlog.base was emitted alongside docs/planning/backlogs/).
  • plugin/entities/backlog/base.yaml (the template) has file.inFolder("planning/backlog") (singular) baked into its filter, which is inconsistent with the plural entity directory.
  • This is a recent regression — the --obsidian flag was added by task 2026-05-19-add-obsidian-bases-setup-flag.

Proposed

Section titled “Proposed”

/sdlc:setup --obsidian writes exactly one Bases file per entity, into the same directory the structure step created, with a filter that points at that same directory. For backlog specifically: docs/planning/backlogs/backlogs.base containing file.inFolder("planning/backlogs").

Pick ONE naming convention for backlog (most likely plural to match the other three entity types) and apply it consistently across the script’s output path, the template’s filter, and any other plugin artifacts that hard-code the directory name.

Approach

Section titled “Approach”
  1. Decide singular vs plural for backlog (recommend plural — it matches epics/, milestones/, tasks/).
  2. Update scripts/setup_planning.py so the Obsidian step writes <plural>/<plural>.base for every entity, derived from the same plural form used to create the directory. Audit whether the script currently has a hard-coded singular form somewhere or whether the plural form just doesn’t apply to backlog.
  3. Update plugin/entities/backlog/base.yaml filter to file.inFolder("planning/backlogs").
  4. Audit other entity base.yaml templates for the same singular/plural inconsistency.
  5. Verify against a fresh project: /sdlc:setup --obsidian should produce four <plural>/<plural>.base files, no orphan dirs.

Files to touch

Section titled “Files to touch”
  • scripts/setup_planning.py — fix the path the Obsidian step writes to so it matches the entity directory the structure step creates.
  • plugin/entities/backlog/base.yaml — change filter to file.inFolder("planning/backlogs").
  • Possibly plugin/entities/backlog/ rename to match plural? (Unclear whether the schema discovery keys off directory name or schema contents — investigate during implementation.)

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: Running /sdlc:setup --obsidian on a fresh project produces docs/planning/backlogs/backlogs.base (plural), not docs/planning/backlog/backlog.base.
  • AC-2: The Bases file’s filter references the same directory it lives in (planning/backlogs).
  • AC-3: Running /sdlc:setup --obsidian --force on the dev repo itself overwrites the existing singular paths into the plural form (or a separate cleanup step is documented).
  • AC-4: No orphan docs/planning/backlog/ (singular) directory remains after a fresh setup run.

Out of scope

Section titled “Out of scope”
  • Migrating projects that already have content in docs/planning/backlog/ to the plural form. Cleanup of the dev repo’s own duplicate dir is in scope; broader migration tooling is not.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”
  • Surfaced 2026-05-20 by /sdlc:task-work running 2026-05-19-obsidian-vault-id-uri in sksizer/rust-path-opener. The /sdlc:setup --obsidian step there produced docs/planning/backlog/backlog.base alongside the structure step’s docs/planning/backlogs/ directory, requiring a manual move
    • filter edit before continuing.

← Back to Tasks