Compare commits

...
3 Commits
Author SHA1 Message Date
OthmanAdi bb3a21ab0d docs: update CONTRIBUTORS, CHANGELOG, README for v2.29.0 2026-03-24 20:00:46 +01:00
Ahmad Othman Ammar Adi. 02a4ad6034 feat(templates): add analytics workflow template (#115)
feat(templates): add analytics workflow template
2026-03-24 19:57:14 +01:00
Matt Van Horn c7f89340d6 feat(templates): add analytics workflow template
Add domain-specific planning templates for data analytics and
exploration workflows. The existing 5-phase template assumes a
software development cycle - analytics sessions need different
phases (Data Discovery, Exploratory Analysis, Hypothesis Testing,
Synthesis) and different tracking structures (Data Sources,
Hypothesis Log, Query Results, Statistical Findings).

New files:
- templates/analytics_task_plan.md: 4-phase analytics plan
- templates/analytics_findings.md: data source and hypothesis tracking

Modified files:
- scripts/init-session.sh: add --template/-t flag
- scripts/init-session.ps1: add -Template parameter

Usage: ./init-session.sh --template analytics
Default behavior is unchanged when flag is omitted.

Relates to #103
2026-03-24 10:18:00 -07:00
7 changed files with 361 additions and 19 deletions
+37
View File
@@ -2,6 +2,43 @@
All notable changes to this project will be documented in this file.
## [2.29.0] - 2026-03-24
### Added
- **Analytics workflow template** (PR #115 by @mvanhorn, addresses #103)
- New `--template analytics` flag on `init-session.sh` and `init-session.ps1`
- `templates/analytics_task_plan.md` with 4 analytics-specific phases: Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis
- `templates/analytics_findings.md` with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
- Analytics-specific `progress.md` generates a Query Log table instead of Test Results
- Default behavior unchanged; existing users are not affected
### Usage
```bash
./scripts/init-session.sh --template analytics my-project
```
### Thanks
- @mvanhorn (Matt Van Horn) for implementing the analytics template that @sedlukha requested in #103
---
## [2.28.0] - 2026-03-22
### Added
- **Traditional Chinese (zh-TW) skill variant** (PR #113 by @waynelee2048)
- Fully translated SKILL.md, templates, and scripts under `skills/planning-with-files-zht/`
- Localized hooks, check-complete, init-session, and session-catchup scripts
### Thanks
- @waynelee2048 for the Traditional Chinese translation
---
## [2.27.0] - 2026-03-20
### Added
+9 -2
View File
@@ -82,6 +82,13 @@ These amazing people have contributed code, documentation, or significant improv
- Added Pi Agent support with full skill integration
- **Impact:** Expands the skill to the Pi Agent ecosystem
- **[@mvanhorn](https://github.com/mvanhorn)** (Matt Van Horn) - [PR #115](https://github.com/OthmanAdi/planning-with-files/pull/115)
- Added analytics workflow template with `--template analytics` flag on `init-session.sh` and `init-session.ps1`
- Created `analytics_task_plan.md` with 4 analytics-specific phases (Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis)
- Created `analytics_findings.md` with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
- Analytics-specific `progress.md` with Query Log replacing Test Results
- **Impact:** Extends the planning pattern to data analytics workflows (addresses #103)
### Other Contributors
- **[@popey](https://github.com/popey)** - [PR #83](https://github.com/OthmanAdi/planning-with-files/pull/83)
@@ -185,6 +192,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 26+ and growing!
**Total Contributors:** 27+ and growing!
*Last updated: March 22, 2026*
*Last updated: March 24, 2026*
+7 -5
View File
@@ -42,18 +42,20 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.26.2
### Current Version: v2.29.0
| Version | Highlights |
|---------|------------|
| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing — hooks now register correctly |
| **v2.26.1** | Fix: session catchup after `/clear` — path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
| **v2.29.0** | Analytics workflow template: `--template analytics` flag for data exploration sessions (thanks @mvanhorn!) |
| **v2.28.0** | Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!) |
| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing, hooks now register correctly |
| **v2.26.1** | Fix: session catchup after `/clear`, path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
| **v2.26.0** | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |
| **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |
| **v2.18.1** | Copilot garbled characters complete fix |
| **v2.18.0** | BoxLite sandbox runtime integration |
| **v2.17.0** | Mastra Code support + all IDE SKILL.md spec fixes |
| **v2.16.1** | Copilot garbled characters fix — PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
| **v2.16.1** | Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
| **v2.16.0** | GitHub Copilot hooks support (thanks @lincolnwan!) |
| **v2.27.0** | Kiro Agent Skill layout (thanks @EListenX!) |
| **v2.15.1** | Session catchup false-positive fix (thanks @gydx6!) |
@@ -152,7 +154,7 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)
[![Mastra Code](https://img.shields.io/badge/Mastra%20Code-Skills-00BCD4)](https://code.mastra.ai)
[![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)
[![Version](https://img.shields.io/badge/version-2.26.2-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![Version](https://img.shields.io/badge/version-2.29.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
## Quick Install
+52 -6
View File
@@ -1,17 +1,34 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# Templates: default, analytics
param(
[string]$ProjectName = "project"
[string]$ProjectName = "project",
[string]$Template = "default"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Resolve template directory (skill root is one level up from scripts/)
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$SkillRoot = Split-Path -Parent $ScriptDir
$TemplateDir = Join-Path $SkillRoot "templates"
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
$Template = "default"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
} else {
@"
# Task Plan: [Brief Description]
## Goal
@@ -56,6 +73,7 @@ Phase 1
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
}
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
} else {
@"
# Findings & Decisions
## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
}
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
if ($Template -eq "analytics") {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Data Discovery
- **Started:** $DATE
### Actions Taken
-
### Query Log
| Query | Result Summary | Interpretation |
|-------|---------------|----------------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
} else {
@"
# Progress Log
## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
}
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
+65 -6
View File
@@ -1,17 +1,48 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
# Usage: ./init-session.sh [--template TYPE] [project-name]
# Templates: default, analytics
set -e
PROJECT_NAME="${1:-project}"
# Parse arguments
TEMPLATE="default"
PROJECT_NAME="project"
while [[ $# -gt 0 ]]; do
case "$1" in
--template|-t)
TEMPLATE="$2"
shift 2
;;
*)
PROJECT_NAME="$1"
shift
;;
esac
done
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Resolve template directory (skill root is one level up from scripts/)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
# Validate template
if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
TEMPLATE="default"
fi
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
cp "$TEMPLATE_DIR/analytics_task_plan.md" task_plan.md
else
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
@@ -56,6 +87,7 @@ Phase 1
| Error | Resolution |
|-------|------------|
EOF
fi
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
@@ -63,7 +95,10 @@ fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
cp "$TEMPLATE_DIR/analytics_findings.md" findings.md
else
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
@@ -83,6 +118,7 @@ if [ ! -f "findings.md" ]; then
## Resources
-
EOF
fi
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
@@ -90,7 +126,29 @@ fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
if [ "$TEMPLATE" = "analytics" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Data Discovery
- **Started:** $DATE
### Actions Taken
-
### Query Log
| Query | Result Summary | Interpretation |
|-------|---------------|----------------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
else
cat > progress.md << EOF
# Progress Log
## Session: $DATE
@@ -110,6 +168,7 @@ if [ ! -f "progress.md" ]; then
| Error | Resolution |
|-------|------------|
EOF
fi
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
+85
View File
@@ -0,0 +1,85 @@
# Findings & Decisions
<!--
WHAT: Knowledge base for your analytics session. Stores data sources, hypotheses, and results.
WHY: Context windows are limited. This file is your "external memory" for analytical work.
WHEN: Update after ANY discovery, especially after running queries or viewing charts.
-->
## Data Sources
<!--
WHAT: Every data source you connected to, with schema details and quality notes.
WHY: Knowing where your data came from and its limitations is critical for reproducibility.
EXAMPLE:
| user_events | PostgreSQL prod replica | 2.3M rows | user_id, event_type, ts | 0.2% null user_id |
| revenue.csv | Finance team export | 45K rows | account_id, mrr, churn_date | Complete, no nulls |
-->
| Source | Location | Size | Key Fields | Quality Notes |
|--------|----------|------|------------|---------------|
| | | | | |
## Hypothesis Log
<!--
WHAT: Each hypothesis you tested, the method used, and the result.
WHY: Structured tracking prevents p-hacking and makes your reasoning auditable.
EXAMPLE:
| H1: Churn > 50% for low-activity users | Chi-squared test | Confirmed (p=0.003) | High |
| H2: Feature X correlates with retention | Pearson correlation | Rejected (r=0.08) | High |
-->
| Hypothesis | Test Method | Result | Confidence |
|------------|-------------|--------|------------|
| | | | |
## Query Results
<!--
WHAT: Key queries you ran and what they revealed.
WHY: Queries are ephemeral - if you don't write down the results, they're lost on context reset.
WHEN: After EVERY significant query. Don't wait.
EXAMPLE:
### Churn rate by activity segment
Query: SELECT activity_bucket, COUNT(*), AVG(churned) FROM user_segments GROUP BY 1
Result: Low activity: 62% churn, Medium: 28%, High: 8%
Interpretation: Strong inverse relationship between activity and churn
-->
<!-- Record query, result summary, and interpretation for each significant query -->
## Statistical Findings
<!--
WHAT: Formal statistical test results with all relevant metrics.
WHY: Recording p-values, effect sizes, and confidence intervals makes results reproducible.
EXAMPLE:
| Chi-squared (churn ~ activity) | p=0.003 | Cramer's V=0.31 | Reject null: activity segments differ significantly in churn |
| Pearson (feature_x ~ retention) | p=0.42 | r=0.08 | Fail to reject: no meaningful correlation |
-->
| Test | p-value | Effect Size | Conclusion |
|------|---------|-------------|------------|
| | | | |
## Technical Decisions
<!--
WHAT: Analytical method choices with reasoning.
EXAMPLE:
| Use log transform on revenue | Right-skewed distribution, normalizes for parametric tests |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!-- URLs, file paths, documentation links -->
-
## Visual/Browser Findings
<!--
CRITICAL: Update after viewing charts, dashboards, or browser results.
Multimodal content doesn't persist in context - capture as text immediately.
-->
-
---
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
+106
View File
@@ -0,0 +1,106 @@
# Task Plan: [Analytics Project Description]
<!--
WHAT: Roadmap for a data analytics or exploration session.
WHY: Analytics workflows have different phases than software development — hypothesis testing,
data quality checks, and statistical validation don't map to a generic build cycle.
WHEN: Create this FIRST before starting any data exploration. Update after each phase.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to learn or produce.
EXAMPLE: "Determine which user segments have the highest churn risk using last 90 days of activity data."
-->
[One sentence describing the analytical objective]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are. Update this as you progress.
-->
Phase 1
## Phases
### Phase 1: Data Discovery
<!--
WHAT: Connect to data sources, understand schemas, assess data quality.
WHY: Bad data produces bad analysis. This phase prevents wasted effort on unreliable inputs.
-->
- [ ] Identify and connect to data sources
- [ ] Document schemas and field descriptions in findings.md
- [ ] Assess data quality (nulls, duplicates, outliers, date ranges)
- [ ] Estimate dataset size and query performance
- **Status:** in_progress
### Phase 2: Exploratory Analysis
<!--
WHAT: Distributions, correlations, outliers, initial patterns.
WHY: Understanding the shape of your data before testing hypotheses prevents false conclusions.
-->
- [ ] Compute summary statistics for key variables
- [ ] Visualize distributions and relationships
- [ ] Identify outliers and anomalies
- [ ] Document initial patterns in findings.md
- **Status:** pending
### Phase 3: Hypothesis Testing
<!--
WHAT: Formalize hypotheses, run statistical tests, validate findings.
WHY: Moving from "it looks like X" to "we can confidently say X" requires structured testing.
-->
- [ ] Formalize hypotheses from exploratory phase
- [ ] Select appropriate statistical tests
- [ ] Run tests and record results in findings.md
- [ ] Validate findings against holdout data or alternative methods
- **Status:** pending
### Phase 4: Synthesis & Reporting
<!--
WHAT: Summarize findings, create visualizations, document conclusions.
WHY: Analysis without clear communication is wasted work. This phase produces the deliverable.
-->
- [ ] Summarize key findings with supporting evidence
- [ ] Create final visualizations
- [ ] Document conclusions and recommendations
- [ ] Note limitations and areas for further investigation
- **Status:** pending
## Hypotheses
<!--
WHAT: Questions you're investigating, stated as testable hypotheses.
WHY: Explicit hypotheses prevent fishing expeditions and keep analysis focused.
EXAMPLE:
1. Users who logged in < 3 times in the last 30 days have > 50% churn rate (H1)
2. Feature X adoption correlates with retention (r > 0.3) (H2)
-->
1. [Hypothesis to test]
2. [Hypothesis to test]
## Decisions Made
<!--
WHAT: Analytical decisions with reasoning (e.g., choosing a test, filtering criteria).
EXAMPLE:
| Use median instead of mean | Revenue data is heavily right-skewed |
| Filter to last 90 days | Earlier data uses a different tracking schema |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
EXAMPLE:
| Query timeout on raw table | 1 | Added date partition filter |
| Null join keys in user_events | 2 | Inner join instead of left join, documented data loss |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
- Update phase status as you progress: pending -> in_progress -> complete
- Re-read this plan before major analytical decisions
- Log ALL errors - they help avoid repetition
- Write query results and visual findings to findings.md immediately