Skip to content

Comments

Restructure softwaredev ways into taxonomy with expanded semantic matching#30

Merged
aaronsb merged 3 commits intomainfrom
restructure-softwaredev-taxonomy
Feb 17, 2026
Merged

Restructure softwaredev ways into taxonomy with expanded semantic matching#30
aaronsb merged 3 commits intomainfrom
restructure-softwaredev-taxonomy

Conversation

@aaronsb
Copy link
Owner

@aaronsb aaronsb commented Feb 17, 2026

Summary

  • Reorganize flat softwaredev/ (20 ways) into five clusters: architecture/, code/, delivery/, environment/, docs/
  • Add BM25 semantic matching to 11 regex-only ways, expanding coverage from 7 to 18 semantically-scored ways
  • Expand activation test from 6 to 8 test steps covering newly-semantic ways and co-activation
  • Fix all path references (symlinks, docs, hook comments, test harnesses)

Motivated by well-engineered-repos analysis identifying coverage gaps when the softwaredev ways are measured against a comprehensive repository documentation model.

Taxonomy

softwaredev/
├── architecture/   (adr, adr-context, design)
├── code/           (errors, performance, quality, security, testing)
├── delivery/       (commits, github, migrations, patches, release)
├── environment/    (config, debugging, deps, ssh)
└── docs/           (docs parent, api child)

Test results

Metric Before After
Semantic ways 7 18
Fixture accuracy 26/32 (81%) 48/54 (89%)
Fixture FP 0 0
Integration accuracy 27/31 27/31
Integration FP 0 0
Activation test steps 6 8

Follow-up issues

Test plan

  • Fixture tests pass (48/54, 0 FP)
  • Integration tests pass (27/31, 0 FP)
  • ADR tool symlink works (docs/scripts/adr list)
  • No stale path references (except legacy ADR-013, intentionally untouched)
  • Run activation test in fresh session (steps 4 and 5 are new)

…atching

Reorganize flat softwaredev/ ways into five clusters:
- architecture/ (adr, adr-context, design)
- code/ (errors, performance, quality, security, testing)
- delivery/ (commits, github, migrations, patches, release)
- environment/ (config, debugging, deps, ssh)
- docs/ (docs parent, api child)

Add BM25 description + vocabulary to 11 regex-only ways, expanding
semantic matching from 7 to 18 ways. Fixture tests: 48/54 (0 FP).
Integration tests: 27/31 (0 FP). No regressions from restructure.

Fix ADR tool symlink, update all path references in docs, hook
comments, test harness, and integration tests. Legacy ADR-013
left untouched as historical record.
Add steps 4 (newly-semantic way via BM25) and 5 (co-activation of
related ways) to the live activation test. Update test README with
18-way corpus baseline and new coverage scenarios.

8 test steps covering: regex, established BM25, new BM25, co-activation,
negative control, subagent injection, subagent negative.
The subagent negative test was failing because general-purpose subagents
inherit parent conversation context — Performance Way from Step 4 was
visible via context sharing, not SubagentStart injection. The injection
pipeline correctly produced no stash for an irrelevant prompt.

Updated Step 8 to distinguish injection (SubagentStart hook) from
context inheritance (Task tool parent sharing).
@aaronsb aaronsb merged commit 3ff8f1a into main Feb 17, 2026
1 check passed
@aaronsb aaronsb deleted the restructure-softwaredev-taxonomy branch February 17, 2026 15:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant