jbr870/devwork-skills
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Consider grouping journals (and reports) under subfolders in the feature folder #5

New issue
Open
opened 2026-04-20 19:37:19 +00:00 by jbr870 · 0 comments
jbr870 commented 2026-04-20 19:37:19 +00:00
Owner
Copy link

Split off from #3 (path mismatch fix, now resolved in 4ff8a84) to track the optional naming/layout question separately.

Question

Should journal (and possibly report) artifacts move from flat paths at the feature-folder root into grouped subfolders?

Current (flat):

$FEATURE_FOLDER/
  SREQ.md
  PREQ.md
  dev-journal-WU-1.md
  dev-journal-WU-2.md
  a11y-journal.md
  api-journal.md
  code-report.md
  a11y-report.md
  ...

Alternative (grouped):

$FEATURE_FOLDER/
  SREQ.md
  PREQ.md
  journals/
    dev-WU-1.md
    dev-WU-2.md
    a11y.md
    api.md
  reports/
    code.md
    a11y.md
    ...

Why it matters

  • A feature folder accumulates 15+ files at the root across SREQ/PREQ, per-work-unit dev journals, and per-domain validation journals + reports. Flat layout gets noisy as artifact types grow.
  • Consumers would glob $FEATURE_FOLDER/journals/dev-*.md instead of dev-journal-WU-*.md — cleaner separation between naming and grouping.
  • Worth aligning with the broader local-first artifact structure being designed elsewhere before doing a second migration.

Arguments against

  • Flat paths tab-complete and shell-script more easily.
  • No functional bug — this is cosmetic. Churn cost = updating producer (/develop), all consumers (learning-analysis, simplify-report, validation skills), and template docs.
  • Current filenames self-describe (dev-journal-WU-1.md); under journals/ they shrink to dev-WU-1.md which only reads well with the folder context.

Dependencies / related

  • #1 — YAML frontmatter for journals; both issues touch journal structure, worth deciding together.
  • Whatever the "local-first artifact structure" direction produces — this should be decided in that context, not in isolation.

Decision needed

Batch with #1 or defer until local-first artifact layout is defined. Non-blocking for any current feature work.

Split off from #3 (path mismatch fix, now resolved in 4ff8a84) to track the optional naming/layout question separately. ## Question Should journal (and possibly report) artifacts move from flat paths at the feature-folder root into grouped subfolders? **Current (flat):** ``` $FEATURE_FOLDER/ SREQ.md PREQ.md dev-journal-WU-1.md dev-journal-WU-2.md a11y-journal.md api-journal.md code-report.md a11y-report.md ... ``` **Alternative (grouped):** ``` $FEATURE_FOLDER/ SREQ.md PREQ.md journals/ dev-WU-1.md dev-WU-2.md a11y.md api.md reports/ code.md a11y.md ... ``` ## Why it matters - A feature folder accumulates 15+ files at the root across SREQ/PREQ, per-work-unit dev journals, and per-domain validation journals + reports. Flat layout gets noisy as artifact types grow. - Consumers would glob `$FEATURE_FOLDER/journals/dev-*.md` instead of `dev-journal-WU-*.md` — cleaner separation between naming and grouping. - Worth aligning with the broader local-first artifact structure being designed elsewhere before doing a second migration. ## Arguments against - Flat paths tab-complete and shell-script more easily. - No functional bug — this is cosmetic. Churn cost = updating producer (/develop), all consumers (learning-analysis, simplify-report, validation skills), and template docs. - Current filenames self-describe (`dev-journal-WU-1.md`); under `journals/` they shrink to `dev-WU-1.md` which only reads well *with* the folder context. ## Dependencies / related - #1 — YAML frontmatter for journals; both issues touch journal structure, worth deciding together. - Whatever the "local-first artifact structure" direction produces — this should be decided in that context, not in isolation. ## Decision needed Batch with #1 or defer until local-first artifact layout is defined. Non-blocking for any current feature work.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jbr870/devwork-skills#5
No description provided.