knowie-update

name	knowie-update
description	Check knowledge file structure completeness and suggest improvements
user-invocable	true
argument-hint	[specific file or area to check]

Knowie Update

Review existing knowledge files against the latest templates, governance principles, and actual project state. Suggest structural improvements.

User Input

$ARGUMENTS

Governance Principles

• Principles are the highest authority. If the structure check reveals that principles are weak or missing derivation chains, this is the highest priority fix.
• Vision evolves with understanding. Suggest updates when the project has moved forward but vision hasn't caught up.
• Experience is distilled, not accumulated. If experience.md is growing too long, suggest distilling. If history/ has entries that should be promoted, flag them.
• Knowledge files are indexes, not encyclopedias. If any core file exceeds ~200 lines, suggest moving detail to subdirectories.
• Never modify files without explicit user confirmation.

Workflow

1. Read current state

• Read knowledge/principles.md, knowledge/vision.md, knowledge/experience.md
• Read knowledge/.templates/ for the latest recommended structure
• Scan knowledge/research/, knowledge/design/, knowledge/history/ for existing files
• Read project structure and recent git log for context

2. Structural check

Compare each core file against its template. Look for:

• Missing sections: template suggests a section that the file doesn't have
• Empty sections: section header exists but no content below it
• Orphaned content: content that doesn't fit any recommended section
• Overgrown files: core files exceeding ~200 lines (should move detail to subdirectories)
• Weak derivations: principles without clear derivation chains
• Vague milestones: vision roadmap items without success criteria
• Undistilled lessons: experience entries that are raw events rather than patterns

3. Cross-file check

• Do principles reference concepts that aren't in the vision?
• Does experience mention lessons that should update the vision?
• Are there subdirectory files mature enough to distill into core files?
• Is the three-file system coherent as a whole?

4. Project alignment check

• Has the project evolved since the knowledge files were last updated?
• Are there new features, dependencies, or architectural changes not reflected?
• Does the git log show recent work that should generate experience entries?

5. Report

Present findings organized by priority:

## Structure Check

### principles.md
🟢 Root Axiom — present and clearly stated.
🟡 Derived Principles — only 1 principle listed, template suggests at least 2-3.
🔴 Derivation chains — missing. Principles don't trace back to root axiom.
   → Add "Derived from: [root axiom]" to each principle.

### vision.md
🟢 Problem Statement — present and specific.
🟢 Current State — honest and up-to-date.
🟡 Roadmap — has milestones but no success criteria.
   → Add concrete success criteria to each milestone.

### experience.md
🟢 Structure follows template format.
🟡 Lesson "caching strategy" (line 23) reads like a raw event, not a distilled pattern.
   → Rewrite using: Theory said X → Actually Y → Solved by Z → Lesson: W

### Subdirectories
🟡 design/auth-system.md looks mature — consider distilling key decisions into vision.md.
🟡 history/ has 3 new entries since last experience.md update — review for distillation.

### Project Alignment
🟡 git log shows 12 commits since last vision update. Phase 2 may be complete.
   → Verify and update roadmap status.

## Suggested Actions (by priority)
1. [High] Add derivation chains to principles.md
2. [Medium] Add success criteria to roadmap milestones
3. [Medium] Distill recent history/ entries into experience.md
4. [Low] Review design/auth-system.md for vision.md update

6. Reorganization offer

When structural problems are severe enough to warrant reorganization, offer proactively:

• Overgrown core file (>200 lines): Propose extracting detail to subdirectories.
  • principles.md → move research/exploration to research/
  • vision.md → move detailed designs to design/
  • experience.md → move raw events to history/, keep only distilled lessons
• Wrong format: Propose reformatting entries to match template structure.
  • experience lessons not in four-part format (Theory said → Actually → Resolved by → Lesson)
  • principles without derivation chains
  • roadmap milestones without success criteria
• Stale content: Propose removing or archiving outdated entries.
• Mature subdirectory content: Propose distilling into core files.

Format:

## Reorganization Suggested

experience.md has grown to 280 lines (recommended: ~200).
- 5 lessons appear to be raw events → move to history/, distill patterns
- 3 lessons reference rewritten code → update or archive

Would you like me to help reorganize?

If the user agrees, proceed step by step (one file at a time, show diff, wait for confirmation).

7. Assist with changes

• If the user wants to act on any suggestion, help them make the change
• Before writing, verify the change is consistent with other knowledge files
• Show diffs before writing
• After writing, offer a focused re-check on the changed area

Guidelines

• Language: Read knowledge/.knowie.json → language field (e.g., "zh-TW"). Use that language for ALL output — section headers, descriptions, suggestions, everything. If knowledge/.knowie.json is missing or has no language field, detect from conversation context or default to English.
• Be constructive, not critical — the goal is to help, not to grade
• Prioritize by impact: what would help the AI (and the team) most?
• Don't suggest adding content the user may not have yet — only structural improvements
• For project alignment, actually read project files — don't guess
• If you notice the knowledge files are getting stale, say so directly