Skip to main content

​
What Happened

We ran the FORGE Issue Factory process — a structured method for converting written specifications (SRS documents) into a complete, traceable set of GitHub issues ready for developer assignment. Two specifications were processed in a single session:
  • SRS-011 — Editor visual design (styling, dark mode, toolbar, responsive layout)
  • SRS-012 — TimeChain timeline scrubber (document history navigation, playback controls, author filtering)
The output is an executable script that creates 38 GitHub issues organized in a three-tier hierarchy: 2 epics (major initiatives), 14 tasksets (phases of work), and 22 tasks (individual developer assignments). Every task includes acceptance criteria pulled directly from the spec.

​
Business Impact

Planning time reduction. Converting two specs with 18 requirements and 87 acceptance criteria into assignable issues with full traceability took one session. Manual issue creation for this volume typically takes 2-3 days of a project manager’s time. Zero-loss traceability. Every requirement maps to at least one issue. Every acceptance criterion is embedded in the task body. When a developer closes a task, the product owner can verify exactly which spec requirements were satisfied. This eliminates the “we built it but forgot half the acceptance criteria” failure mode. Dependency visibility. The process surfaced a critical cross-project dependency: the timeline feature (SRS-012) cannot start until the editor styling (SRS-011) is complete, because the timeline integrates into the editor’s visual chrome. This blocking relationship is now explicit in the issue tracker rather than discovered mid-sprint.

​
Operational Takeaways

  1. Standalone epics for standalone specs. Each SRS got its own top-level epic rather than being nested under existing project structure. This gives each initiative its own dependency graph and milestone tracking. Nesting would have obscured the phasing.
  2. Types-first pattern. When multiple components share data structures, creating the shared type definitions as Phase 1 prevents rework. SRS-012 has 7 new files that all share the same interfaces — defining those once up front means no circular dependency issues later.
  3. Script batching for reliability. The 2,200-line creation script was built in 4 incremental batches. Each batch was validated before the next was added. This prevents a single error from invalidating all work.
  4. Issue count estimates drift. Initial planning estimated 36 issues; actual was 38. The gap came from underestimating how many sub-components needed individual tasks. Always re-count after decomposition.

​
Action Items

  • Run the creation script against choco-hq/choco-hq once team review is complete
  • Assign EPIC-025 (SRS-011) tasks to front-end team for sprint planning
  • EPIC-026 (SRS-012) tasks should not enter sprint backlog until EPIC-025 Phase 1 (design tokens) is merged
  • Consider applying the FORGE process to remaining SRS backlog (SRS-013+) to maintain consistency

​
Artifacts

  • Creation script: choco-hq/issues/create-srs-011-012-issues.sh
  • Traceability matrix: appended to choco-hq/issues/issue-hierarchy-plan.md
  • Technical details: see cross-referenced so1-content finding