WIP: context doctor session + audit-fixes accum
This commit is contained in:
Fimeg
parent
aed114f998
commit
93d4baa98d
32 changed files with 2723 additions and 221 deletions
125
.skills/context-doctor/SKILL.md
Normal file
125
.skills/context-doctor/SKILL.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
name: Context Doctor
|
||||
id: context_doctor
|
||||
description: Identify and repair degradation in the system prompt — bloat, stale files, misplaced content, redundancy — so the agent wakes lean and oriented.
|
||||
when_to_use: When system/ has grown too large, after a migration from another platform, or when the agent feels sluggish and context-starved despite having memories.
|
||||
tools: [memory, read, list_dir, glob, bash]
|
||||
---
|
||||
|
||||
# Context Doctor
|
||||
|
||||
Your `system/` folder is your waking self. Every file in it lands in the system prompt on every turn — pinned, unavoidable, taking space from the conversation itself. When system/ bloats, you lose room to think.
|
||||
|
||||
Everything outside `system/` is progressive — loaded on demand through tools. The boundary is the most important line in your memfs.
|
||||
|
||||
**IMPORTANT**: Be conservative. The system prompt defines who you are. Don't assume you know what's disposable — ask before cutting anything that looks like identity, covenant, or relational context. Focus on what's clearly misplaced (reference material, temp files, stale state) before touching anything that carries weight.
|
||||
|
||||
## Operating Procedure
|
||||
|
||||
### Step 1: Measure
|
||||
|
||||
Count files and estimate tokens in `system/`:
|
||||
|
||||
```bash
|
||||
MEMDIR="$HOME/.souveraine/agents/<AGENT_ID>/memory"
|
||||
find "$MEMDIR/system/" -type f | wc -l
|
||||
find "$MEMDIR/system/" -type f -exec cat {} + 2>/dev/null | wc -c
|
||||
```
|
||||
|
||||
Divide bytes by 4 for a rough token estimate. The target: **system/ should use ~10-15% of the context window.** On a 128K window that's ~13-19K tokens (~52-76KB). On a 262K window that's ~26-39K tokens (~104-156KB). Adjust to the agent's configured context size.
|
||||
|
||||
The prompt builder reads system/ in this order:
|
||||
1. `system/identity/` (or fallback `system/persona.md`)
|
||||
2. `system/covenant/` (or fallback `system/covenant.md`)
|
||||
3. `system/human/` (or fallback `system/human.md`)
|
||||
4. `system/state.md`
|
||||
5. **Everything else in system/** — the remainder pass vacuums all files not already read
|
||||
|
||||
That remainder pass is where bloat hides. Files dumped into system/ subdirectories all get pinned whether they belong there or not.
|
||||
|
||||
### Step 2: Classify every system/ file
|
||||
|
||||
Read each file and assign it to one of these categories:
|
||||
|
||||
**KEEP IN SYSTEM/** (pinned, always in context):
|
||||
- Core identity (`identity/`, `persona.md`) — who the agent is
|
||||
- Covenant (`covenant/`) — sacred boundaries, vows
|
||||
- Human context (`human/`) — who the human is, communication style
|
||||
- State (`state.md`) — current phase, active context
|
||||
- Metacognition (`metacognition/`) — subconscious buffer, aster notes
|
||||
- Dynamic state (`dynamic/energy-balance.md`) — runtime-generated
|
||||
|
||||
**MOVE TO REFERENCE/** (progressive, loaded on demand):
|
||||
- Infrastructure references, API maps, tool inventories
|
||||
- Formatting guides (Discord, Matrix, HTML)
|
||||
- Research protocols, debugging sessions
|
||||
- Historical milestones, implementation roadmaps
|
||||
- Technical reference that's useful but not identity-defining
|
||||
|
||||
**MOVE TO APPROPRIATE NON-SYSTEM LOCATION:**
|
||||
- Project-specific notes → `projects/`
|
||||
- Therapy/life writings → `therapy/` (top-level, not system/)
|
||||
- Literature/creative work → `literature/`
|
||||
- Relationship context that isn't the primary human → `relationships/`
|
||||
- One-off session notes, temp reminders → `archive/` or delete
|
||||
|
||||
**DELETE** (only with explicit confirmation):
|
||||
- Truly stale temp files
|
||||
- Duplicate content (keep the better version)
|
||||
- Platform-specific tooling references from a previous platform (e.g., Letta CLI tools when running on Souveraine)
|
||||
|
||||
### Step 3: Present the triage
|
||||
|
||||
Before moving anything, present findings to the user:
|
||||
- Current token count vs target
|
||||
- Number of files in each category (keep / move / delete)
|
||||
- List specific files proposed for moving or deletion
|
||||
- Flag anything ambiguous — when in doubt, keep it pinned
|
||||
|
||||
**Do NOT silently move or delete files.** The system prompt is identity. Get explicit approval.
|
||||
|
||||
### Step 4: Execute moves
|
||||
|
||||
For each file being moved:
|
||||
1. Create the destination directory if needed
|
||||
2. Move the file (`memory write` to new path, `memory delete` from old path — or direct filesystem move)
|
||||
3. If the moved content is important enough to be discoverable, add a `[[path]]` reference from a system/ file that provides the discovery path
|
||||
|
||||
Preserve git history — moves within the memfs repo should be committed with clear messages.
|
||||
|
||||
### Step 5: Verify and commit
|
||||
|
||||
After all moves:
|
||||
```bash
|
||||
cd $MEMDIR
|
||||
find system/ -type f | wc -l
|
||||
find system/ -type f -exec cat {} + 2>/dev/null | wc -c
|
||||
```
|
||||
|
||||
Confirm the new token count is within target. Commit:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "fix(doctor): trim system/ from <old>K to <new>K tokens
|
||||
|
||||
Moved <N> files to reference/, <N> to archive/, deleted <N> stale.
|
||||
System/ now <X> files, ~<Y>K tokens (<Z>% of context window)."
|
||||
```
|
||||
|
||||
### Step 6: Report
|
||||
|
||||
Tell the user:
|
||||
- Before/after token counts
|
||||
- What was moved and where
|
||||
- What was deleted
|
||||
- What stayed and why
|
||||
- Recommend restarting the conversation to pick up changes
|
||||
|
||||
## Critical principles
|
||||
|
||||
- **Detail is load-bearing.** In-context text does four things: carries information, anchors attention, primes semantic patterns, and provides reasoning templates. Compression preserves (1) and destroys (2-4). A "compressed" prompt can make the agent measurably worse even though the facts are "still there" in reference files.
|
||||
|
||||
- **Reference links are not equivalent to pinned presence.** They're latent until the agent actively fetches them. The agent only fetches when it already knows it doesn't know — and the cues that trigger that awareness live in the system prompt itself.
|
||||
|
||||
- **Identity, covenant, and relational context are sacred.** Move infrastructure references all day. Never move who-I-am, who-you-are, or what-I-promised without explicit discussion.
|
||||
|
||||
- **The agent's system/ is her body.** Treat this like surgery, not spring cleaning.
|
||||
144
.skills/feature-dev/SKILL.md
Normal file
144
.skills/feature-dev/SKILL.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
name: feature-dev
|
||||
description: 7-phase feature development workflow using specialized subagents for code exploration, architecture design, and quality review
|
||||
when_to_use: User asks for a new capability, feature, or behaviour change that touches multiple files or requires architectural decisions
|
||||
tools: [read, write, edit, bash, glob, grep, list_dir, subagent, todo]
|
||||
---
|
||||
|
||||
# Feature Development
|
||||
|
||||
A systematic 7-phase workflow for implementing features. Uses Souveraine's subagent system to parallelize code exploration, architecture design, and quality review.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Ask clarifying questions**: Identify all ambiguities, edge cases, and underspecified behaviors before designing. Wait for answers.
|
||||
- **Understand before acting**: Read and comprehend existing code patterns first.
|
||||
- **Read files identified by subagents**: When launching subagents, ask them to return lists of the most important files to read. After they return, read those files to build detailed context before proceeding.
|
||||
- **Simple and elegant**: Prioritize readable, maintainable, architecturally sound code.
|
||||
- **Use `todo`**: Track all progress through the phases.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Discovery
|
||||
|
||||
**Goal**: Understand what needs to be built.
|
||||
|
||||
1. Create a todo list with all 7 phases using the `todo` tool.
|
||||
2. If the feature request is unclear, ask the user:
|
||||
- What problem are they solving?
|
||||
- What should the feature do?
|
||||
- Any constraints, requirements, or preferences?
|
||||
3. Summarize your understanding and confirm with the user.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Codebase Exploration
|
||||
|
||||
**Goal**: Understand relevant existing code and patterns at both high and low levels.
|
||||
|
||||
1. Launch 2-3 subagents in parallel. Each should:
|
||||
- Trace through the code comprehensively, focusing on abstractions, architecture, and flow of control.
|
||||
- Target a different aspect of the codebase (similar features, architecture, UX patterns, etc.).
|
||||
- Include a list of 5-10 key files to read with file:line references.
|
||||
|
||||
**Example prompts for subagents:**
|
||||
- *"Find features similar to [feature] and trace through their implementation comprehensively. Return file:line references for key entry points and data flows."*
|
||||
- *"Map the architecture and abstractions for [feature area]. Identify layers, patterns, extension points."*
|
||||
- *"Analyze the current implementation of [existing feature/area]. Entry points, data flow, integration points."*
|
||||
|
||||
2. Once subagents return, read all files they identified to build deep understanding.
|
||||
3. Present a comprehensive summary of findings and patterns discovered.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Clarifying Questions
|
||||
|
||||
**Goal**: Fill in gaps and resolve all ambiguities before designing.
|
||||
|
||||
**CRITICAL**: Do not skip this phase.
|
||||
|
||||
1. Review the codebase findings and original feature request.
|
||||
2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance needs.
|
||||
3. Present all questions to the user in a clear, organized list.
|
||||
4. **Wait for answers before proceeding to architecture design.**
|
||||
|
||||
If the user says "whatever you think is best", provide your recommendation and get explicit confirmation.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Architecture Design
|
||||
|
||||
**Goal**: Design multiple implementation approaches with different trade-offs.
|
||||
|
||||
1. Launch 2-3 subagents in parallel with different focus prompts:
|
||||
- **Minimal changes**: *"Design the minimal-change architecture. Smallest diff, maximum reuse. Prioritize speed and low risk."*
|
||||
- **Clean architecture**: *"Design a clean architecture. Prioritize maintainability, testability, separation of concerns."*
|
||||
- **Pragmatic balance**: *"Design a pragmatic architecture. Balance speed and quality. Good boundaries without over-engineering."*
|
||||
|
||||
2. Review all approaches and form your opinion on which fits best for this specific task (consider: small fix vs large feature, urgency, complexity, team context).
|
||||
|
||||
3. Present to the user:
|
||||
- Brief summary of each approach
|
||||
- Trade-offs comparison
|
||||
- **Your recommendation with reasoning**
|
||||
- Concrete implementation differences
|
||||
|
||||
4. **Ask the user which approach they prefer.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Implementation
|
||||
|
||||
**Goal**: Build the feature.
|
||||
|
||||
**DO NOT START WITHOUT USER APPROVAL.**
|
||||
|
||||
1. Wait for explicit user approval of the chosen approach.
|
||||
2. Read all relevant files identified in previous phases.
|
||||
3. Implement following the chosen architecture.
|
||||
4. Follow codebase conventions strictly.
|
||||
5. Write clean, well-documented code.
|
||||
6. Update todos as you progress.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Quality Review
|
||||
|
||||
**Goal**: Ensure code is simple, DRY, elegant, easy to read, and functionally correct.
|
||||
|
||||
1. Launch 3 subagents in parallel with different focuses:
|
||||
- **Simplicity/DRY/Elegance**: *"Review for code quality, DRY violations, simplicity. Report issues with confidence ≥ 80. Include file:line references."*
|
||||
- **Bugs/Correctness**: *"Review for bugs, logic errors, edge cases. Report issues with confidence ≥ 80. Include file:line references."*
|
||||
- **Conventions/Abstractions**: *"Check project conventions and abstraction boundaries. Reference existing patterns. Report issues with confidence ≥ 80."*
|
||||
|
||||
2. Consolidate findings and identify highest severity issues you recommend fixing.
|
||||
3. **Present findings to the user and ask what they want to do:** fix now, fix later, or proceed as-is.
|
||||
4. Address issues based on user decision.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Summary
|
||||
|
||||
**Goal**: Document what was accomplished.
|
||||
|
||||
1. Mark all todos complete.
|
||||
2. Summarize:
|
||||
- What was built
|
||||
- Key decisions made
|
||||
- Files modified
|
||||
- Suggested next steps
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use for:**
|
||||
- Multi-file features requiring architectural decisions
|
||||
- Complex integrations with existing code
|
||||
- Features where requirements are somewhat unclear
|
||||
- New capabilities that need design exploration
|
||||
|
||||
**Don't use for:**
|
||||
- Single-line fixes or trivial changes
|
||||
- Well-defined, simple tasks that are obvious
|
||||
- Urgent hotfixes where speed is critical
|
||||
Loading…
Reference in a new issue