docs: Refactor documentation and remove book citations from code#6
Merged
Conversation
- Create REFERENCES.md with comprehensive design patterns and book sources - Document recursive self-improvement approach (system used itself to discover patterns) - Remove direct book citations from code comments (follow AGENTS.md guidelines) - Replace book references with pattern names and link to REFERENCES.md - Create SETUP.md with detailed installation and seeding instructions - Restructure README.md for better priority and succinctness (41% reduction) - Move detailed setup steps from README.md to dedicated SETUP.md Files modified: - src/application/container.ts - src/domain/services/concept-search-service.ts - src/domain/interfaces/repositories/chunk-repository.ts - src/infrastructure/lancedb/searchable-collection-adapter.ts - src/infrastructure/document-loaders/document-loader.ts - src/infrastructure/document-loaders/pdf-loader.ts - src/domain/exceptions.ts - src/__tests__/integration/test-db-setup.ts - src/__tests__/test-helpers/test-data.ts Pattern references preserved: Repository, Domain Service, Adapter, Strategy, Exception Hierarchy, Test Fixture, Test Data Builder, Composition Root. Code comments now focus on 'what' and 'why' specific to this codebase, while REFERENCES.md provides broader context and book sources.
m2ux
added a commit
that referenced
this pull request
Nov 27, 2025
Implement ConceptRepository interface using LanceDB: - findByName: Exact concept lookup by name - findRelated: Vector search for similar concepts - searchConcepts: Text-based concept search Note: findByName() still uses string interpolation in WHERE clause. This will be addressed in security fixes task (Issue #6). Related: Architecture Review 2025-11-14, Task 1.8
m2ux
added a commit
that referenced
this pull request
Nov 27, 2025
Escape single quotes in user input before SQL WHERE clause: - Replace single quotes with doubled quotes (SQL standard escaping) - Prevents SQL injection in findByName() query Example attack prevented: Input: "test' OR '1'='1" Before: WHERE concept = 'test' OR '1'='1' (injection!) After: WHERE concept = 'test'' OR ''1''=''1' (safe) Fixes Issue #6 from architecture review (SQL injection vulnerability). Related: Architecture Review 2025-11-14, Task 3.2, Issue #6
m2ux
added a commit
that referenced
this pull request
Nov 27, 2025
docs: Refactor documentation and remove book citations from code
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR refactors the project documentation to follow best practices by:
Motivation
Code comments should document the system as it exists, not the process that created it.
Previously, book references were scattered throughout code comments. This approach cluttered code with process attribution rather than technical substance.
Key Changes
📚 New Files
REFERENCES.md (173 lines) - Comprehensive design patterns and book sources catalog
SETUP.md (302 lines) - Dedicated installation and configuration guide
✏️ Modified Files
README.md (287 lines, down from 487) - 41% reduction
9 source files - Removed book citations from comments
Recursive Self-Improvement
REFERENCES.md documents how concept-rag was built using its own capabilities:
concept_searchto find relevant patterns during developmentbroad_chunks_searchto explore related conceptsThis validates the practical utility of RAG systems for software development.
Benefits
✅ Cleaner code comments focused on technical substance
✅ Better documentation organization and navigation
✅ Highlights unique recursive self-improvement value
✅ Follows AGENTS.md guidelines
✅ All pattern references preserved and centralized
Testing
Design Patterns Preserved
Repository, Domain Service, Adapter, Strategy, Composition Root, Exception Hierarchy, Test Fixture, Test Data Builder
Ready for review! 🚀
Full PR description available in:
.ai/summaries/2025-11-17-pr-documentation-refactor.md