Mark/easystitch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Decompose: Stale documentation cleanup (project_summary, module_structure, roadmap) #39

New issue
Closed
opened 2026-06-22 16:23:20 +00:00 by Mark · 1 comment
Mark commented 2026-06-22 16:23:20 +00:00
Owner
Copy link

Stale documentation cleanup — project_summary, module_structure, roadmap

Context

Three docs in docs/ are out of sync with the current codebase:

  1. docs/project_summary.md — claims DST-only MVP, doesn't list
    PES/EXP/JEF generators, references a top-level config/ directory
    that doesn't exist, says "57 passing tests" when pytest collects 3.
  2. docs/module_structure.md — listed 8+ phantom modules in a
    previous open issue (#3 was already closed as fixed, but the fix
    may not have caught everything).
  3. docs/roadmap.md — Phases 1–3 marked complete; Phase 4 (GUI)
    is now decoupled from the main service.

A new contributor reading these gets a wrong mental model of what
easyStitch is.

Decomposition

Three independent doc fixes, each a focused PR.

P1: project_summary.md rewrite

Goal: Replace the stale "MVP COMPLETE" framing with a current
description of easyStitch.

Files:

  • Modify: docs/project_summary.md

Acceptance:

  • Module tree matches find src -type f -name "*.py" | sort.
  • Status line is accurate (active development, not "MVP complete").
  • Stale claims about test counts and format support are corrected.
  • PES/EXP/JEF generators are mentioned.
  • The Qt6 GUI is mentioned but flagged as not on the service critical
    path.

Why first: this is the doc most likely to be read first by a new
contributor. Getting it right is the highest-value single fix.

P2: module_structure.md sync

Goal: Make sure the module-structure doc matches the actual file
layout. Audit the doc against find src and git log to find any
phantom modules or missing ones.

Files:

  • Modify: docs/module_structure.md

Acceptance:

  • Every file under src/ is either described in the doc or explicitly
    excluded with a reason (e.g. "dead code, see issue #44").
  • Every module described in the doc exists at the stated path.
  • The doc includes a "Last verified" date so future readers know when
    the audit was last done.

Depends on: P1 (project_summary should agree).

P3: roadmap.md update

Goal: Update the roadmap to reflect the current state and the
new service direction.

Files:

  • Modify: docs/roadmap.md

Acceptance:

  • Phases 1–3 are updated to reflect the actual current scope (not just
    DST; PES/EXP/JEF; not 57 tests; etc.).
  • A new "Phase 5: Service deployment" section is added covering the
    HTTP service (issue #31), the ThreadCraft integration
    (ThreadCraft #11), and the operational concerns from issues #40, #43.
  • The GUI (Phase 4) is decoupled — it's a separate repo (per issue #44),
    not part of this roadmap.
  • A "Last updated" date at the top of the doc.

Depends on: P1, P2 (so the roadmap doesn't reference stale structure
or counts).

Out of scope

  • Other docs in docs/ (api_documentation.md, developer_guide.md, etc.)
    may also be stale, but those are lower-priority for new-contributor
    onboarding. File separate tickets for them if needed.
  • Generating docs from code (a Python script that emits structural
    overview from src/) is a larger refactor; out of scope for this
    cleanup.
# Stale documentation cleanup — project_summary, module_structure, roadmap ## Context Three docs in `docs/` are out of sync with the current codebase: 1. **`docs/project_summary.md`** — claims DST-only MVP, doesn't list PES/EXP/JEF generators, references a top-level `config/` directory that doesn't exist, says "57 passing tests" when pytest collects 3. 2. **`docs/module_structure.md`** — listed 8+ phantom modules in a previous open issue (#3 was already closed as fixed, but the fix may not have caught everything). 3. **`docs/roadmap.md`** — Phases 1–3 marked complete; Phase 4 (GUI) is now decoupled from the main service. A new contributor reading these gets a wrong mental model of what easyStitch is. ## Decomposition Three independent doc fixes, each a focused PR. ### P1: project_summary.md rewrite **Goal:** Replace the stale "MVP COMPLETE" framing with a current description of easyStitch. **Files:** - Modify: `docs/project_summary.md` **Acceptance:** - Module tree matches `find src -type f -name "*.py" | sort`. - Status line is accurate (active development, not "MVP complete"). - Stale claims about test counts and format support are corrected. - PES/EXP/JEF generators are mentioned. - The Qt6 GUI is mentioned but flagged as not on the service critical path. **Why first:** this is the doc most likely to be read first by a new contributor. Getting it right is the highest-value single fix. --- ### P2: module_structure.md sync **Goal:** Make sure the module-structure doc matches the actual file layout. Audit the doc against `find src` and `git log` to find any phantom modules or missing ones. **Files:** - Modify: `docs/module_structure.md` **Acceptance:** - Every file under `src/` is either described in the doc or explicitly excluded with a reason (e.g. "dead code, see issue #44"). - Every module described in the doc exists at the stated path. - The doc includes a "Last verified" date so future readers know when the audit was last done. **Depends on:** P1 (project_summary should agree). --- ### P3: roadmap.md update **Goal:** Update the roadmap to reflect the current state and the new service direction. **Files:** - Modify: `docs/roadmap.md` **Acceptance:** - Phases 1–3 are updated to reflect the actual current scope (not just DST; PES/EXP/JEF; not 57 tests; etc.). - A new "Phase 5: Service deployment" section is added covering the HTTP service (issue #31), the ThreadCraft integration (ThreadCraft #11), and the operational concerns from issues #40, #43. - The GUI (Phase 4) is decoupled — it's a separate repo (per issue #44), not part of this roadmap. - A "Last updated" date at the top of the doc. **Depends on:** P1, P2 (so the roadmap doesn't reference stale structure or counts). ## Out of scope - Other docs in `docs/` (api_documentation.md, developer_guide.md, etc.) may also be stale, but those are lower-priority for new-contributor onboarding. File separate tickets for them if needed. - Generating docs from code (a Python script that emits structural overview from `src/`) is a larger refactor; out of scope for this cleanup.
Mark changed title from docs/project_summary.md is stale and contradicts the codebase to Decompose: Stale documentation cleanup (project_summary, module_structure, roadmap) 2026-06-22 16:30:52 +00:00
Mark commented 2026-06-22 16:31:31 +00:00
Author
Owner
Copy link

This issue has been decomposed into the following sub-issues:

# Title Phase Scope
#57 Decompose: Stale documentation cleanup (project_summary, mod Goal: Replace the stale "MVP COMPLETE" framing with a current description of
#58 Decompose: Stale documentation cleanup (project_summary, mod Goal: Make sure the module-structure doc matches the actual file layout. Aud
#59 Decompose: Stale documentation cleanup (project_summary, mod Goal: Update the roadmap to reflect the current state and the new service di

Each sub-issue has been labeled with triage-approved and is ready for queue routing.

This issue has been decomposed into the following sub-issues: | # | Title | Phase Scope | |---|-------|-------------| | #57 | Decompose: Stale documentation cleanup (project_summary, mod | **Goal:** Replace the stale "MVP COMPLETE" framing with a current description of | | #58 | Decompose: Stale documentation cleanup (project_summary, mod | **Goal:** Make sure the module-structure doc matches the actual file layout. Aud | | #59 | Decompose: Stale documentation cleanup (project_summary, mod | **Goal:** Update the roadmap to reflect the current state and the new service di | Each sub-issue has been labeled with `triage-approved` and is ready for queue routing.
Mark closed this issue 2026-06-22 16:31:31 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
blocked:children

   
blocked:depends-101

Depends on Mark/easystitch#101 landing first.

  
blocked:depends-103

Depends on corresponding issue landing first.

  
blocked:depends-104

Depends on corresponding issue landing first.

  
blocked:needs-attention

Session stuck or abandoned, needs human review

  
blocked:needs-decision

   
blocked:no-changes

   
blocked:preflight

Held by kilo-gsd preflight until lint-cleanup lands

  
bug

Something is not working correctly

  
chore

Config/cleanup items (reporter lane)

  
feature-request

   
in-progress

Claimed by kilo-gsd pipeline

  
lint-cleanup

Repo-wide lint cleanup ticket — kilo-gsd preflight hard-gate

  
needs-decompose

   
performance

   
quality

   
quickfix

   
security/medium

Medium severity security issue

  
triage-approved

Triage: approved for fixer pipeline

No labels
blocked:children
blocked:depends-101
blocked:depends-103
blocked:depends-104
blocked:needs-attention
blocked:needs-decision
blocked:no-changes
blocked:preflight
bug
chore
feature-request
in-progress
lint-cleanup
needs-decompose
performance
quality
quickfix
security/medium
triage-approved
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
Mark/easystitch#39
No description provided.