What is the Bite and Blow strategy?

Bite drafts small chunks of a file; Blow synthesizes all drafts into a high-density global map to guide evolution.

Where are drafts stored and what is final deliverable?

Drafts are stored in drafts/ as MAP_[filename].md; final deliverable is GLOBAL_MAP.md (plus a Glossary).

What if the project is huge or in agentic mode?

In agentic mode, the final map may reside in brain/; output remains English and Markdown.

Project Evolver Mapper

Scanned

npx machina-cli add skill Vit0lze/Project-Evolver-Framework/project-evolver-mapper --openclaw

Files (1)

SKILL.md

2.4 KB

Project Evolver Mapper

This skill enables systematic mapping of complex codebases to prepare for future evolution. It uses an incremental strategy to digest large projects and produces a high-density global map.

1. Proactive Vision Interview (The "Why")

Goal: Deduce or extract the 'Project Purpose' before mapping.

Deduce: Briefly scan root files (README, package.json, main entry) to guess the project's core purpose.
Ask: Present this deduction to the user.

"I see this appears to be a [Project Type] aiming to [Goal]. Is this accurate? What is your primary evolution goal (e.g., refactor, feature add, rewrite)?"
Validate: Do not proceed to deep mapping until the user confirms the vision.

2. Chained Mapping Workflow

Execute this loop to map the codebase.

Phase A: Scan & Strategy

List all files.
Identify large files (>30k tokens) that need splitting.
Plan the mapping order (typically Core -> Utils -> Features).

Phase B: Chunk & Draft ("Bite")

For each file (or chunk):

Split using scripts/chunk_reader.py if the file is too large.

python scripts/chunk_reader.py path/to/large_file.py --size 30000

Analyze the chunk. Load references/mapping-patterns.md for templates.
Draft a momentary map in drafts/.
- Create drafts/MAP_[filename].md.
- Extract: Logic Anchors, Dependencies, Breaking Points.

Phase C: Synthesize ("Blow")

Combine all draft maps into a single GLOBAL_MAP.md in the root (or brain/ folder if in agentic mode).
Format: strict Markdown.
Language: All output MUST be in English.

3. Output Requirements

Drafts: Temporary, verbose analysis stored in drafts/.
GLOBAL_MAP.md: The final deliverable. High density, low fluff.
Glossary: Include a glossary of domain terms found in the code.

4. Constraint Checklist

"Context Safety First": Never read entire large repos at once.
"English Only": Analysis must be in English.
"Evolution Ready": Focus on changeability (coupling, cohesion), not just description.

Source

git clone https://github.com/Vit0lze/Project-Evolver-Framework/blob/main/Skill Files/project-evolver-mapper/SKILL.mdView on GitHub

Overview

Project Evolver Mapper enables systematic, incremental mapping of large codebases to prepare for future evolution. It applies a Bite and Blow strategy: digest the project in manageable chunks and produce a high-density GLOBAL_MAP.md that guides refactors, feature adds, or rewrites.

How This Skill Works

Technically it follows a Proactive Vision Interview to define the project purpose, then a three-phase workflow. Phase A inventories files and plans the mapping order; Phase B splits large files with `scripts/chunk_reader.py`, analyzes chunks, and drafts maps in `drafts/`; Phase C synthesizes drafts into a single `GLOBAL_MAP.md` in the root (or `brain/` in agentic mode), in strict English Markdown.

When to Use It

When you need to understand or migrate a complex codebase that exceeds context limits.
When planning a refactor, feature addition, or rewrite for a large project.
When mapping a project for future work or onboarding new maintainers.
When breaking down a monolith into modules with a structured map.
When you require a high-density global map (GLOBAL_MAP.md) and a glossary of domain terms.

Quick Start

Step 1: Conduct the Proactive Vision Interview to deduce project purpose and goals.
Step 2: Run Phase A to list files and plan mapping order.
Step 3: For each chunk, run `scripts/chunk_reader.py`, draft maps in `drafts/`, then synthesize into `GLOBAL_MAP.md`.

Best Practices

Start with the Proactive Vision Interview to lock project goals.
Inventory files early and plan the mapping order in Phase A.
Split large files with `scripts/chunk_reader.py` and draft incrementally in `drafts/`.
Keep the drafts verbose but organized and synthesize into a single GLOBAL_MAP.md.
Ensure output is in English and include a glossary of domain terms.

Example Use Cases

Map a 10k+ file monorepo to prepare for microservices architecture.
Refactor a legacy CMS by producing a detailed evolution map for incremental changes.
Plan a major feature set addition to a complex analytics project using a global map.
Prepare for a complete rewrite of an old API by outlining dependencies and breaking points.
Onboard new engineers with a clear GLOBAL_MAP.md and glossary from the codebase.

Frequently Asked Questions

Add this skill to your agents