COMPACTION.md

Read your project entry point in AGENTS.md and review the entire .agents knowledge base before making changes.

Goal:
Compact the knowledge base into a maintainable architectural memory system.

The knowledge base should preserve:

* Current architecture
* Current conventions
* Current routing
* Current visual/theme decisions
* Current troubleshooting knowledge that remains relevant today
* Owner-confirmed decisions
* Upgrade risks
* Maintenance warnings

The knowledge base should NOT preserve:

* Investigation timelines
* Debugging narratives
* Failed experiments
* Step-by-step troubleshooting history
* Temporary states that no longer exist
* Historical project snapshots
* Verification logs once a decision is established
* Repeated information already documented elsewhere

Specific instructions:

1. Session Notes Compaction

Review .agents/session-notes.md.

For each completed work item:

* Extract the final decision.
* Extract any current maintenance warning.
* Extract any architectural consequence.

Move those items into:

* decisions.md
* troubleshooting.md
* theme-overrides.md
* architecture.md

as appropriate.

Then remove the historical narrative.

Examples of content to remove:

* timelines
* root-cause investigations that are already resolved
* browser testing logs
* HTTP verification logs
* build output logs
* server restart history
* iterative CSS experiments
* discussion of approaches that were ultimately rejected

After compaction, session-notes.md should contain only:

* unresolved work
* active investigations
* work currently in progress

If no active investigations remain, replace the file with a short note explaining that historical work has been compacted into architectural documents.

2. Troubleshooting Compaction

Review .agents/troubleshooting.md.

For resolved issues:

Keep:

* symptom summary
* final root cause
* final resolution
* current maintenance guidance

Remove:

* investigation chronology
* obsolete implementation details
* superseded fixes
* references to deleted code paths
* duplicated verification records

Troubleshooting should answer:

"What do I need to know if this problem appears again?"

not

"How did we discover the answer?"

3. Theme Override Compaction

Review .agents/theme-overrides.md.

Remove:

* historical investigations
* rejected approaches
* obsolete selector history
* deleted component implementation details

Retain:

* current ownership
* current selectors
* current rationale
* upgrade risks
* maintenance warnings

Document only the current state.

4. Knowledge Base De-duplication

Review:

* README.md
* project-map.md
* routing.md
* site-style-guide.md

If the same information appears in multiple files:

Keep the most detailed version in the most appropriate file.

Replace duplicates with brief references.

Avoid maintaining the same architectural facts in multiple locations.

5. Decisions Archive Entry

Add a new entry to .agents/decisions.md:

Date: <INSERT TODAY'S DATE IN TZ=AMERICA/NEW_YORK>

Decision:
Knowledge Base Compaction

Rationale:
The .agents knowledge base should function as long-term project memory, not a historical troubleshooting journal.

Policy:

* Preserve conclusions.
* Preserve architecture.
* Preserve conventions.
* Preserve warnings.
* Preserve upgrade risks.
* Preserve owner-confirmed decisions.
* Remove historical investigation narratives once issues are resolved.
* Prefer Git history and commit history for implementation archaeology.

Expected Outcome:

The .agents knowledge base should become:

* Smaller
* Faster to read
* Easier for future agents to onboard
* Focused on current project reality rather than historical discovery

At completion:

Provide:

* estimated line count reduction
* files compacted
* files left unchanged
* any information intentionally preserved despite age because it still affects maintenance decisions