refactor: migrate to topic-first directory structure#15
Merged
Conversation
Move workflow documentation from docs/specs/{type}/{topic}/ to
docs/workflow/{topic}/ for topic-first organization.
Changes:
- All workflow artifacts now live together in docs/workflow/{topic}/
- Single files: discussion.md, specification.md, plan.md
- Multiple files: use pluralized subdirectory (e.g., discussions/)
- Updated all 5 skills and 3 commands with new paths
- Updated README and CLAUDE.md documentation
This keeps all artifacts for a feature in one place, making it easier
to navigate and understand the complete picture for any topic.
leeovery
added a commit
that referenced
this pull request
Apr 20, 2026
…ack to text Two retrieval-layer fixes: - cmdStatus used to shell out to 'manifest get' per spec topic for the superseded-spec consistency check — N processes for N specs, ~5s on 50-spec repos. Now loads the full manifest tree once via 'manifest list' and resolves topic statuses in memory. Same behaviour, O(1) processes. (deferred #6) - searchHybrid previously returned zero hits when Orama's similarity post-filter masked a query with no strong vector matches, even when BM25 would have found good text matches. Fall back to a fulltext search before returning empty. Search results can only improve. (deferred #15) Closes deferred-issues #6, #15.
leeovery
added a commit
that referenced
this pull request
Apr 21, 2026
Added while auditing the ESM-resolution build change. Imports the built bundle directly and exercises every Orama API path we use: - create store with vector schema - insert (100 docs across 3 work units × 3 phases) - searchFulltext with where filter - searchVector with similarity threshold - searchHybrid normal path - searchHybrid → fulltext fallback (the #15 fix) - removeByFilter - saveStore / loadStore (MsgPack round-trip) - metadata write/read - all search modes on the loaded store Not wired into the automated suite — run ad hoc when verifying bundle-level changes. Caught one bogus assertion in my own earlier smoke pass (Orama does not echo embedding fields on search hits by design) and confirmed no behaviour change between CJS- and ESM-resolved bundles.
leeovery
added a commit
that referenced
this pull request
Apr 25, 2026
Empirical probing of Orama's hybrid mode shows the deferred-issue #15 concern doesn't manifest. With a flat or poor-quality vector and a tight similarity threshold (e.g. 0.99), hybrid still returns BM25- driven hits — text matches come through regardless. The only way to get zero hybrid hits is when the term itself doesn't match anything, at which point a fulltext fallback also returns zero. The defensive fallback added in commit 33303da was therefore dead code: in every realistic scenario the original hybrid call already returns the right thing. Removing it. deferred-issues.md #15 reclassified RESOLVED → WITHDRAWN with the empirical evidence and a pointer to the brief commit history. kb-smoke.cjs: relabelled the previous '#15 fallback' check. The assertion still holds — hybrid surfaces BM25 hits even with weak vector matches — but it now describes what's actually being proven (Orama hybrid handles this natively) rather than the now-removed fallback path. 168/168 CLI + smoke + store + integration green.
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
2 participants
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.
Move workflow documentation from docs/specs/{type}/{topic}/ to
docs/workflow/{topic}/ for topic-first organization.
Changes:
This keeps all artifacts for a feature in one place, making it easier
to navigate and understand the complete picture for any topic.