writing-analysis-plans

Writing Analysis Plans

Convert an approved analytical design into a detailed, executable plan with no placeholders, no ambiguity, and no implicit context.

Checklist

1. Load the design doc — read the spec from docs/datapowers/specs/
2. Identify all work streams — EDA, validation, feature engineering, modeling, evaluation, reporting
3. Decompose into tasks — 15-30 minutes each, independently executable
4. Write each task with full specificity — no placeholders, no "similar to above"
5. Add verification step to every task — how to confirm completion
6. Self-review the plan — check coverage, placeholder scan, task size
7. Save plan — docs/datapowers/plans/YYYY-MM-DD-<topic>-plan.md
8. User reviews plan — confirm before execution begins

Task Decomposition Rules

Every task must specify:

• Exact files or data to read
• Exact outputs to produce (file names, variable names)
• Exact code or commands (no "write code to do X")
• Verification — what to run/check to confirm success

❌ Bad Task

Task 3: Feature engineering
- Create features for the churn dataset
- Handle missing values
- Encode categoricals

This is useless. An agent cannot execute this without guessing.

✅ Good Task

Task 3: Numeric feature preprocessing
Files: data/train.csv, data/test.csv

Steps:
1. Load X_train from data/train_features.csv (saved in Task 2)
2. For columns ['age', 'tenure_months', 'monthly_charges']:
   - Clip outliers at [Q1 - 3×IQR, Q3 + 3×IQR] using training set quantiles
   - Impute with median (fit on X_train, transform X_test)
   - Apply StandardScaler (fit on X_train, transform X_test)
3. Save fitted imputer to artifacts/imputer_numeric.pkl
4. Save fitted scaler to artifacts/scaler_numeric.pkl
5. Save transformed training features to data/X_train_numeric.csv
6. Save transformed test features to data/X_test_numeric.csv

Verification:
- Run: python -c "import pandas as pd; df=pd.read_csv('data/X_train_numeric.csv'); print(df.isnull().sum())"
- Expected: all zeros (no nulls after imputation)
- Run: python -c "import pandas as pd; df=pd.read_csv('data/X_train_numeric.csv'); print(df.describe())"
- Expected: means near 0, stds near 1 (after scaling)