planning-with-files | SkillBundle

Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk." This skill helps you plan, track, and checkpoint complex tasks that span multiple files, APIs, or sessions.

WHEN TO USE THIS SKILL

ALWAYS use this skill when:

Task involves 3+ phases or steps
Implementing wrappers for multiple REST APIs
Migrating or refactoring code across multiple files
Research tasks requiring exploration
Any task requiring >5 tool calls
Work that may span multiple sessions
Tasks with dependencies between components

Skip this skill for:

Simple questions or quick lookups
Single-file edits
Tasks completable in 1-2 tool calls

The Core Principle

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

-> Anything important gets written to disk.
-> After ~50 tool calls, you FORGET original goals.
-> Re-reading plan files keeps goals in your attention window.

File Structure

All planning files go in .agent_cache/<task-name>/:

.agent_cache/
└── <task-name>/
    ├── task_plan.md    # Phases, progress, decisions (YOUR ROADMAP)
    ├── findings.md     # Research, discoveries, technical decisions
    └── progress.md     # Session log, test results, files modified

Naming Convention

Use lowercase with hyphens for <task-name>
Be descriptive but concise
Examples:
- .agent_cache/add-admin-apis/
- .agent_cache/migrate-lakehouse-module/
- .agent_cache/add-direct-lake-functions/

The 3-File Pattern

File	Purpose	When to Update
`task_plan.md`	Phases, progress, current status	After each phase completes
`findings.md`	Research, discoveries, decisions	After ANY discovery
`progress.md`	Session log, test results, errors	Throughout session

Quick Start: Before ANY Complex Task

# 1. Create the planning directory
mkdir -p .agent_cache/<task-name

Critical Rules

Rule 1: Create Plan FIRST

Never start a complex task without task_plan.md. Non-negotiable.

Rule 2: The 2-Action Rule

"After every 2 view/search/explore operations, IMMEDIATELY save key findings to files."

This prevents information from being lost as context grows.

Rule 3: Read Before Decide

Before major decisions, read the plan file. This pushes goals into your attention window.

Rule 4: Update After Act

After completing any phase:

Mark phase status: in_progress -> complete
Log files created/modified
Note any errors encountered

Rule 5: Log ALL Errors

Every error goes in the plan file. This builds knowledge and prevents repetition.

Rule 6: Never Repeat Failures

Track what you tried. Mutate the approach.

The 3-Strike Error Protocol

Workflow: The Agent Loop

Template: task_plan.md

Template: findings.md

Template: progress.md

# Progress Log
 
## Session: [DATE]
 
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
  -
- Files created/modified:
  -
 
### Phase 2: [Title]
- **Status:** pending
- Actions taken:
  -
- Files created/modified:
  -
 
---
 
## Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
|      |          |        |        |
 
---
 
## Commands Run
```bash
# Useful commands executed during this session

Session Notes

 
---
 
## Project-Specific Patterns
 
### For Semantic Link Labs API Wrapper Tasks
 
When implementing REST API wrappers, include in findings.md:
 
```markdown
## API Analysis
| API | Fabric Path | Power BI Path | Notes |
|-----|-------------|---------------|-------|
| list_items | /v1/workspaces/{id}/items | /v1.0/myorg/groups/{id}/... | Paginated |
 
## Implementation Pattern
- Use `_base_api` helper for all REST calls
- Use `resolve_workspace_name_and_id` for workspace resolution
- Use `_create_dataframe` for empty DataFrame initialization
- Return `pandas.DataFrame` for list operations
 
## Required Decorator
- `@log` -- Enable logging and telemetry
 
## Function Naming
| Prefix | Use Case |
|--------|----------|
| `list_` | Retrieves a collection |
| `get_` | Retrieves a single item |
| `create_` | Creates a new resource |
| `update_` | Modifies existing resource |
| `delete_` | Removes a resource |

For Test Writing Tasks

Include in findings.md:

Completion Workflow

After finishing all work:

The 5-Question Reboot Test

When resuming work, verify you can answer:

Question	Answer Source
Where am I?	Current phase in task_plan.md
Where am I going?	Remaining phases
What's the goal?	Goal statement in plan
What have I learned?	findings.md
What have I done?	progress.md

If you can't answer these, read all 3 planning files before continuing.

Read vs Write Decision Matrix

Situation	Action	Reason
Just wrote a file	DON'T read	Content still in context
After 2+ searches	Write findings NOW	Before info is lost
Starting new phase	Read plan/findings	Re-orient context
Error occurred	Read relevant file	Need current state
Resuming after gap	Read ALL planning files	Recover state
Before major decision	Read task_plan.md	Refresh goals

Anti-Patterns

Don't	Do Instead
Start executing immediately	Create plan file FIRST
State goals once and forget	Re-read plan before decisions
Hide errors and retry silently	Log errors to plan file
Stuff everything in context	Store large content in files
Repeat failed actions	Track attempts, mutate approach
Skip testing	Always include test tasks

Example: Adding Admin API Wrappers

task_plan.md

Related Skills

Skill	When to Use
add-function	Adding new API wrapper functions
rest-api-patterns	REST API implementation patterns
write-tests	Writing unit tests
code-style	Running linters and formatters
run-tests	Running pytest locally
github-repo-explore	Finding reference implementations