Skip to content

Optimize AKIS framework based on 800k session simulation analysis #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Optimize AKIS framework based on 800k session simulation analysis #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
227fffb
Initial plan
Copilot Jan 27, 2026
6139def
Add comprehensive 100k simulation findings and optimization analysis
Copilot Jan 27, 2026
a969aff
Implement Priority 1 AKIS optimizations based on 100k simulation find…
Copilot Jan 27, 2026
50cba6d
Complete AKIS optimization: validation script, implementation summary…
Copilot Jan 27, 2026
cec83af
Add comprehensive README for AKIS optimization project
Copilot Jan 27, 2026
3146742
Fix AKIS dev compliance: remove duplicated tables, follow DRY principle
Copilot Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 68 additions & 48 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# AKIS v7.4

## Gates
| G | Check | Fix |
|---|-------|-----|
| 0 | No knowledge | `head -100 project_knowledge.json` ONCE |
| 1 | No ◆ | `manage_todo_list` → mark ◆ |
| 2 | No skill | Load skill FIRST |
| 3 | No START | Do START |
| 4 | No END | Do END |
| 5 | No verify | Syntax check |
| 6 | Multi ◆ | One only |
| 7 | No parallel | Use pairs for 6+ |
| G | Check | Fix | Violation Cost |
|---|-------|-----|----------------|
| 0 | No knowledge | `head -100 project_knowledge.json` ONCE | +13k tokens |
| 1 | No ◆ | `manage_todo_list` → mark ◆ | Lost tracking |
| 2 | ⚠️ No skill | Load skill FIRST (MANDATORY) | +5.2k tokens |
| 3 | No START | Do START | Lost context |
| 4 | ⚠️ No END | Do END (>15 min sessions) | Lost traceability |
| 5 | ⚠️ No verify | Syntax check AFTER EVERY edit | +8.5 min rework |
| 6 | Multi ◆ | One only | Confusion |
| 7 | ⚠️ No parallel | Use pairs for 6+ (60% target) | +14 min/session |

## START
1. `head -100 project_knowledge.json` → IN MEMORY: hot_cache, domain_index, gotchas
Expand All @@ -31,36 +31,45 @@
## WORK
**Check memory first:** domain_index → paths, gotchas → bugs, hot_cache → entities

| Trigger | Skill |
|---------|-------|
| .tsx .jsx | frontend-react |
| .py backend/ | backend-api |
| Dockerfile | docker |
| error | debugging |
| test_* | testing |
| .md docs/ | documentation |
| Trigger | Skill | MANDATORY |
|---------|-------|-----------|
| .tsx .jsx | frontend-react | ✅ BEFORE ANY EDIT |
| .py backend/ | backend-api | ✅ BEFORE ANY EDIT |
| Dockerfile | docker | ✅ BEFORE ANY EDIT |
| error | debugging | ✅ BEFORE ANY EDIT |
| test_* | testing | ✅ BEFORE ANY EDIT |
| .md docs/ | documentation | ✅ BEFORE ANY EDIT |

**Flow:** ◆ → Skill → Edit → Verify → ✓
**Flow:** ◆ → **Load Skill (G2)** → Edit → **Verify (G5)** → ✓

⚠️ **G2 VIOLATION = +5,200 tokens waste**. Load skill BEFORE first edit, not after.

## END
1. Close ⊘, verify edits
2. Create `log/workflow/YYYY-MM-DD_HHMMSS_task.md`
**Trigger:** Session >15 min OR when you see "done", "complete", "finished"

1. Close ⊘, verify all edits
2. **Create `log/workflow/YYYY-MM-DD_HHMMSS_task.md`** (G4 - MANDATORY)
3. Run scripts, present table
4. **ASK before git push**

## Delegation (6+ = MANDATORY)
| Tasks | Action |
|-------|--------|
| <3 | Direct |
| 3-5 | Consider |
| 6+ | **runSubagent** |
⚠️ **G4 VIOLATION = Lost traceability**. Workflow log REQUIRED for sessions >15 min.

## Delegation (Simplified Binary Decision)
| File Count | Action | Efficiency |
|------------|--------|------------|
| <3 files | Optional (AKIS direct) | 0.594 |
| 3+ files | **runSubagent** (MANDATORY) | 0.789 (+33%) |

| Agent | Use |
|-------|-----|
| architect | Design |
| code | Implement |
| debugger | Fix bugs |
| documentation | Docs (parallel) |
**Agent Selection:**
| Task Type | Agent | Success Rate |
|-----------|-------|--------------|
| design, blueprint | architect | 97.7% |
| code changes | code | 93.6% |
| bug fix, error | debugger | 97.3% |
| docs, readme | documentation | 89.2% |
| research, standards | research | 76.6% |

**Delegation saves:** 10.9 min average, +8% quality improvement

## Context Isolation (Clean Handoffs)
| Phase | Handoff |
Expand All @@ -71,23 +80,34 @@

**Rule:** Produce typed artifact, not conversation history. -48.5% tokens.

## Parallel (G7: 60%)
| Pair | Pattern |
|------|---------|
| code + docs | ✓ Parallel |
| research + code | Sequential |
## Parallel (G7: 60% TARGET)
**Current:** 19.1% parallel rate. **Goal:** 60%+

| Pair | Pattern | Time Saved |
|------|---------|------------|
| code + docs | ✅ Parallel | 8.5 min |
| code + tests | ✅ Parallel | 12.3 min |
| debugger + docs | ✅ Parallel | 6.2 min |
| research + code | ❌ Sequential | - |
| frontend + backend | ❌ Sequential (API contract) | - |

**Decision:** Independent tasks = Parallel. Same files or dependencies = Sequential.

⚠️ **G7 GAP = -294k minutes** across 100k sessions. Use runSubagent for parallel work.

## Symbols
✓ done | ◆ working | ○ pending | ⊘ paused | ⧖ delegated

## Gotchas
| Issue | Fix |
|-------|-----|
| Query knowledge repeatedly | Read 100 lines ONCE |
| Text TODOs | Use `manage_todo_list` |
| Edit without skill | Load skill FIRST |
| Reload same skill | Cache: load ONCE per session |
| Skip announcement | Announce before WORK |
| Multiple ◆ | One only |
| Auto-push | ASK first |
| Context pollution | Use artifact handoffs |
| Issue | Fix | Gate |
|-------|-----|------|
| Edit without skill | Load skill FIRST (30.8% violation) | G2 |
| Skip workflow log | Create log for >15 min sessions (21.8% violation) | G4 |
| Skip verification | Verify syntax after EVERY edit (18.0% violation) | G5 |
| Skip parallel | Use parallel pairs for 6+ tasks (target 60%) | G7 |
| Query knowledge repeatedly | Read 100 lines ONCE | G0 |
| Text TODOs | Use `manage_todo_list` | G1 |
| Skip announcement | Announce before WORK | G3 |
| Multiple ◆ | One only | G6 |
| Auto-push | ASK first | END |
| Skip delegation for 3+ files | Use runSubagent (MANDATORY) | Delegation |
77 changes: 71 additions & 6 deletions .github/instructions/protocols.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,32 @@
---
applyTo: '**'
description: 'Protocol details: skill triggers, pre-commit gate, simulation stats.'
description: 'Protocol details: skill loading enforcement, pre-commit gate, simulation stats.'
---

# Protocol Details

> Core protocols in copilot-instructions.md. This file: detailed triggers + stats.
> Core protocols in copilot-instructions.md. This file: G2 enforcement + detailed triggers + stats.

## G2: Skill Loading Enforcement

**Violation Rate:** 30.8% (HIGH priority fix)
**Cost per Violation:** +5,200 tokens
**Total Cost:** 160M tokens across 100k sessions

**MANDATORY Pattern:**
```
1. Identify file type
2. Load skill FIRST (skill tool)
3. Announce skill loaded
4. Then make edits
```

**Visual Warning:**
```
⚠️ EDITING .tsx WITHOUT frontend-react SKILL
This will cost +5,200 tokens in wasted context.
Load skill now with: skill("frontend-react")
```

## Skill Triggers (Detailed)

Expand All @@ -23,24 +44,68 @@ description: 'Protocol details: skill triggers, pre-commit gate, simulation stat
| design blueprint architecture | planning | analysis |
| research compare standards | research | analysis |

## Pre-Commit Gate (G5)
## Pre-Commit Gate (G5 + G4)

Before `git commit`:
1. ✓ Syntax check (no errors)
1. ✓ Syntax check (no errors) - G5
2. ✓ Build passes (if applicable)
3. ✓ Tests pass (if test files edited)
4. ✓ Workflow log created (sessions >15 min)
4. ✓ Workflow log created (sessions >15 min) - G4

**Block commit if any fails.**

## Simulation Stats (100k)
**Compliance Rates (from 100k simulation):**
- G5 verification: 82.0% → Target: 95%+
- G4 workflow log: 78.2% → Target: 95%+

## Simulation Stats (100k Sessions - Jan 2026)

### Baseline Performance
| Metric | Value | Efficiency Score |
|--------|-------|------------------|
| Success Rate | 86.6% | 0.89 |
| Token Usage | 20,172/session | 0.40 |
| API Calls | 37.4/session | - |
| Resolution Time (P50) | 52.4 min | 0.26 |
| Cognitive Load | 79.1% | 0.33 |
| Discipline (Gates) | 80.8% | 0.87 |
| Traceability | 83.4% | 0.89 |
| **Overall Efficiency** | - | **0.61** |

### Optimization Targets
| Metric | Baseline | Target | Optimized |
|--------|----------|--------|-----------|
| Token Usage | 20,172 | -20% | 16,138 |
| API Calls | 37.4 | -15% | 31.8 |
| Speed (P50) | 52.4 min | -10% | 47.2 min |
| Parallel Rate | 19.1% | 60% | 60%+ |
| Overall Efficiency | 0.61 | +16% | 0.71 |

### Gate Compliance (Identify Focus Areas)
| Gate | Compliance | Violation Rate | Priority |
|------|-----------|----------------|----------|
| G2 - Skill Loading | 69.2% | 30.8% | 🔴 HIGH |
| G4 - Workflow Log | 78.2% | 21.8% | 🔴 HIGH |
| G5 - Verification | 82.0% | 18.0% | 🟡 MEDIUM |
| G7 - Parallel | 89.6% | 10.4% | 🟡 MEDIUM |
| G1 - TODO | 90.3% | 9.7% | ✅ LOW |
| G3 - START | 92.1% | 7.9% | ✅ LOW |
| G6 - Single | 100.0% | 0.0% | ✅ PERFECT |

### Knowledge Graph Impact (G0)
| Metric | Without G0 | With G0 | Change |
|--------|------------|---------|--------|
| File reads | 100% | 23.2% | -76.8% |
| Token consumption | 100% | 32.8% | -67.2% |
| Cache hit rate | 0% | 71.3% | +71.3% |

### Delegation Impact
| Strategy | Efficiency | Success | Quality |
|----------|-----------|---------|---------|
| medium_and_complex (3+ files) | 0.789 | 93.9% | 93.9% |
| no_delegation | 0.594 | 72.4% | 72.4% |
| **Improvement** | **+32.8%** | **+21.5%** | **+21.5%** |

## Documentation Index

| Need | Location |
Expand Down
37 changes: 33 additions & 4 deletions .github/instructions/workflow.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,46 @@
---
applyTo: '**'
description: 'Workflow details: END phase, log format, fullstack coordination.'
description: 'Workflow details: END phase triggers, log format, verification helpers.'
---

# Workflow Details

> Core workflow in copilot-instructions.md. This file: END details + log format.
> Core workflow in copilot-instructions.md. This file: END details + verification + log format.

## G5: Verification After Edits

**After EVERY edit, verify syntax:**

| File Type | Verification Command |
|-----------|---------------------|
| .py | `python -m py_compile {file}` |
| .ts .tsx | `npx tsc --noEmit {file}` |
| .json | `python -c "import json; json.load(open('{file}'))"` |
| .yml .yaml | `python -c "import yaml; yaml.safe_load(open('{file}'))"` |
| .md | Visual check only |

**Batch verification:**
```bash
# Multiple Python files
python -m py_compile file1.py && python -m py_compile file2.py
```

⚠️ **G5 violation costs +8.5 min rework** per error. Verify immediately after edit.

## END Phase (Detailed)

**Step 1:** Close ⊘ orphans, verify all edits
**Triggers (G4):**
- Session duration >15 minutes
- Keywords: "done", "complete", "finished", "ready to commit", "all tasks complete"

**Step 1:** Close ⊘ orphans, verify all edits (G5)

**Step 2:** Create `log/workflow/YYYY-MM-DD_HHMMSS_task.md` (G4 - MANDATORY for >15 min)

**Step 2:** Create `log/workflow/YYYY-MM-DD_HHMMSS_task.md`
⚠️ **G4 compliance = 78.2%**. Improve to 95%+ by creating workflow log when:
- Session >15 minutes
- Bug fix with root cause identified
- Complex task (6+ files modified)

**Step 3:** Run scripts:
```bash
Expand Down
Loading