Documentation Restructuring and Business Plan Compilation
Summary
The Sokrates project underwent a significant reorganization of its documentation directory to eliminate redundancy and improve content granularity. This process involved migrating the monolithic business plan sections into topical subdirectories and implementing an automated build task via just to compile the final document.
Details
During a maintenance session focused on the docs/ directory, an audit revealed nine sets of duplicate files where content was split between a legacy business-plan/ folder and newer topical directories. The decision was made to treat the topical files as canonical to allow for more granular version control and better organization of the project’s foundational, strategic, and architectural assets.
Redundancy Removal
The following files were identified as exact duplicates and subsequently removed from the repository using git rm to ensure Git correctly tracked the moves as renames (preserving 100% match history):
| Legacy Location | Canonical Topical Location |
|---|---|
docs/business-plan/Section-1.md | docs/foundation/market-analysis.md |
docs/business-plan/Section-2.md | docs/foundation/customer-intelligence.md |
docs/business-plan/Section-3.md | docs/foundation/competitive-landscape.md |
docs/business-plan/Section-4.md | docs/architecture/product-service.md |
docs/business-plan/Section-5.md | docs/business/business-model.md |
docs/business-plan/Section-6.md | docs/strategy/go-to-market.md |
docs/business-plan/Sections_7-10.md | docs/business/operations-financials-risk.md |
Additionally, two top-level architecture files were consolidated into the architecture/ subdirectory:
docs/hyle-architecture.mdwas removed in favor ofdocs/architecture/hyle-eidos.md.docs/sokrates-system-architecture.mdwas removed in favor ofdocs/architecture/system-architecture.md.
Automated Compilation
To maintain the ability to generate a single, cohesive business plan document for stakeholders, a new task was added to the project’s Justfile. The command just docs-compile-bp automates the concatenation of the granular files into a single output file located at dist/business-plan.md.
The compilation process follows a specific sequence to ensure the narrative flow of the business plan:
- Market Analysis:
foundation/market-analysis.md - Customer Intelligence:
foundation/customer-intelligence.md - Competitive Landscape:
foundation/competitive-landscape.md - Product/Service:
architecture/product-service.md - Business Model:
business/business-model.md - Go-to-Market:
strategy/go-to-market.md - Operations, Financials, & Risk:
business/operations-financials-risk.md
The task also prepends a standard frontmatter header to the compiled markdown file. This transition ensures that while the source material is modular and easy to edit, the final deliverable remains consistent and professional.