mirror of
https://github.com/azaion/detections.git
synced 2026-04-22 22:06:32 +00:00
Enhance autopilot documentation and workflows: Add assumptions regarding single project per workspace, update notification sound references, and introduce context budget heuristics for managing session limits. Revise various skill documents to reflect changes in task management, including ticketing and testing processes, ensuring clarity and consistency across the system.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -36,13 +36,30 @@ Fixed paths:
|
||||
- SOLUTION_DIR: `_docs/01_solution/`
|
||||
- PROBLEM_DIR: `_docs/00_problem/`
|
||||
|
||||
Announce resolved paths to user before proceeding.
|
||||
Optional input:
|
||||
|
||||
- FOCUS_DIR: a specific directory subtree provided by the user (e.g., `/document @src/api/`). When set, only this subtree and its transitive dependencies are analyzed.
|
||||
|
||||
Announce resolved paths (and FOCUS_DIR if set) to user before proceeding.
|
||||
|
||||
## Mode Detection
|
||||
|
||||
Determine the execution mode before any other logic:
|
||||
|
||||
| Mode | Trigger | Scope |
|
||||
|------|---------|-------|
|
||||
| **Full** | No input file, no existing state | Entire codebase |
|
||||
| **Focus Area** | User provides a directory path (e.g., `@src/api/`) | Only the specified subtree + transitive dependencies |
|
||||
| **Resume** | `state.json` exists in DOCUMENT_DIR | Continue from last checkpoint |
|
||||
|
||||
Focus Area mode produces module + component docs for the targeted area only. It can be run repeatedly for different areas — each run appends to the existing module and component docs without overwriting other areas.
|
||||
|
||||
## Prerequisite Checks
|
||||
|
||||
1. If `_docs/` already exists and contains files, ASK user: **overwrite, merge, or write to `_docs_generated/` instead?**
|
||||
1. If `_docs/` already exists and contains files AND mode is **Full**, ASK user: **overwrite, merge, or write to `_docs_generated/` instead?**
|
||||
2. Create DOCUMENT_DIR, SOLUTION_DIR, and PROBLEM_DIR if they don't exist
|
||||
3. If DOCUMENT_DIR contains a `state.json`, offer to **resume from last checkpoint or start fresh**
|
||||
4. If FOCUS_DIR is set, verify the directory exists and contains source files — **STOP if missing**
|
||||
|
||||
## Progress Tracking
|
||||
|
||||
@@ -53,7 +70,9 @@ Create a TodoWrite with all steps (0 through 7). Update status as each step comp
|
||||
### Step 0: Codebase Discovery
|
||||
|
||||
**Role**: Code analyst
|
||||
**Goal**: Build a complete map of the codebase before analyzing any code.
|
||||
**Goal**: Build a complete map of the codebase (or targeted subtree) before analyzing any code.
|
||||
|
||||
**Focus Area scoping**: if FOCUS_DIR is set, limit the scan to that directory subtree. Still identify transitive dependencies outside FOCUS_DIR (modules that FOCUS_DIR imports) and include them in the processing order, but skip modules that are neither inside FOCUS_DIR nor dependencies of it.
|
||||
|
||||
Scan and catalog:
|
||||
|
||||
@@ -69,6 +88,7 @@ Scan and catalog:
|
||||
- Entry points (no internal dependents)
|
||||
- Cycles (mark for grouped analysis)
|
||||
- Topological processing order
|
||||
- If FOCUS_DIR: mark which modules are in-scope vs dependency-only
|
||||
|
||||
**Save**: `DOCUMENT_DIR/00_discovery.md` containing:
|
||||
- Directory tree (concise, relevant directories only)
|
||||
@@ -82,14 +102,18 @@ Scan and catalog:
|
||||
{
|
||||
"current_step": "module-analysis",
|
||||
"completed_steps": ["discovery"],
|
||||
"focus_dir": null,
|
||||
"modules_total": 0,
|
||||
"modules_documented": [],
|
||||
"modules_remaining": [],
|
||||
"module_batch": 0,
|
||||
"components_written": [],
|
||||
"last_updated": ""
|
||||
}
|
||||
```
|
||||
|
||||
Set `focus_dir` to the FOCUS_DIR path if in Focus Area mode, or `null` for Full mode.
|
||||
|
||||
---
|
||||
|
||||
### Step 1: Module-Level Documentation
|
||||
@@ -97,6 +121,8 @@ Scan and catalog:
|
||||
**Role**: Code analyst
|
||||
**Goal**: Document every identified module individually, processing in topological order (leaves first).
|
||||
|
||||
**Batched processing**: process modules in batches of ~5 (sorted by topological order). After each batch: save all module docs, update `state.json`, present a progress summary. Between batches, evaluate whether to suggest a session break.
|
||||
|
||||
For each module in topological order:
|
||||
|
||||
1. **Read**: read the module's source code. Assess complexity and what context is needed.
|
||||
@@ -119,7 +145,26 @@ For each module in topological order:
|
||||
**Large modules**: if a module exceeds comfortable analysis size, split into logical sub-sections and analyze each part, then combine.
|
||||
|
||||
**Save**: `DOCUMENT_DIR/modules/[module_name].md` for each module.
|
||||
**State**: update `state.json` after each module completes (move from `modules_remaining` to `modules_documented`).
|
||||
**State**: update `state.json` after each module completes (move from `modules_remaining` to `modules_documented`). Increment `module_batch` after each batch of ~5.
|
||||
|
||||
**Session break heuristic**: after each batch, if more than 10 modules remain AND 2+ batches have already completed in this session, suggest a session break:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
SESSION BREAK SUGGESTED
|
||||
══════════════════════════════════════
|
||||
Modules documented: [X] of [Y]
|
||||
Batches completed this session: [N]
|
||||
══════════════════════════════════════
|
||||
A) Continue in this conversation
|
||||
B) Save and continue in a fresh conversation (recommended)
|
||||
══════════════════════════════════════
|
||||
Recommendation: B — fresh context improves
|
||||
analysis quality for remaining modules
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
Re-entry is seamless: `state.json` tracks exactly which modules are done.
|
||||
|
||||
---
|
||||
|
||||
@@ -238,6 +283,23 @@ Apply corrections inline to the documents that need them.
|
||||
|
||||
**BLOCKING**: Present verification summary to user. Do NOT proceed until user confirms corrections are acceptable or requests additional fixes.
|
||||
|
||||
**Session boundary**: After verification is confirmed, suggest a session break before proceeding to the synthesis steps (5–7). These steps produce different artifact types and benefit from fresh context:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
VERIFICATION COMPLETE — session break?
|
||||
══════════════════════════════════════
|
||||
Steps 0–4 (analysis + verification) are done.
|
||||
Steps 5–7 (solution + problem extraction + report)
|
||||
can run in a fresh conversation.
|
||||
══════════════════════════════════════
|
||||
A) Continue in this conversation
|
||||
B) Save and continue in a new conversation (recommended)
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
If **Focus Area mode**: Steps 5–7 are skipped (they require full codebase coverage). Present a summary of modules and components documented for this area. The user can run `/document` again for another area, or run without FOCUS_DIR once all areas are covered to produce the full synthesis.
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Solution Extraction (Retrospective)
|
||||
@@ -370,9 +432,11 @@ Maintain `DOCUMENT_DIR/state.json`:
|
||||
{
|
||||
"current_step": "module-analysis",
|
||||
"completed_steps": ["discovery"],
|
||||
"focus_dir": null,
|
||||
"modules_total": 12,
|
||||
"modules_documented": ["utils/helpers", "models/user"],
|
||||
"modules_remaining": ["services/auth", "api/endpoints"],
|
||||
"module_batch": 1,
|
||||
"components_written": [],
|
||||
"last_updated": "2026-03-21T14:00:00Z"
|
||||
}
|
||||
@@ -423,16 +487,21 @@ When resuming:
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Bottom-Up Codebase Documentation (8-Step) │
|
||||
├──────────────────────────────────────────────────────────────────┤
|
||||
│ PREREQ: Check _docs/ exists (overwrite/merge/new?) │
|
||||
│ PREREQ: Check state.json for resume │
|
||||
│ MODE: Full / Focus Area (@dir) / Resume (state.json) │
|
||||
│ PREREQ: Check _docs/ exists (overwrite/merge/new?) │
|
||||
│ PREREQ: Check state.json for resume │
|
||||
│ │
|
||||
│ 0. Discovery → dependency graph, tech stack, topo order │
|
||||
│ (Focus Area: scoped to FOCUS_DIR + transitive deps) │
|
||||
│ 1. Module Docs → per-module analysis (leaves first) │
|
||||
│ (batched ~5 modules; session break between batches) │
|
||||
│ 2. Component Assembly → group modules, write component specs │
|
||||
│ [BLOCKING: user confirms components] │
|
||||
│ 3. System Synthesis → architecture, flows, data model, deploy │
|
||||
│ 4. Verification → compare all docs vs code, fix errors │
|
||||
│ [BLOCKING: user reviews corrections] │
|
||||
│ [SESSION BREAK suggested before Steps 5–7] │
|
||||
│ ── Focus Area mode stops here ── │
|
||||
│ 5. Solution Extraction → retrospective solution.md │
|
||||
│ 6. Problem Extraction → retrospective problem, restrictions, AC │
|
||||
│ [BLOCKING: user confirms problem docs] │
|
||||
@@ -441,5 +510,6 @@ When resuming:
|
||||
│ Principles: Bottom-up always · Dependencies first │
|
||||
│ Incremental context · Verify against code │
|
||||
│ Save immediately · Resume from checkpoint │
|
||||
│ Batch modules · Session breaks for large codebases │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user