starred/planning-with-files

Fork 0

mirror of https://github.com/OthmanAdi/planning-with-files.git synced 2026-04-26 00:16:01 +03:00

[GH-ISSUE #69] Documentation inconsistency: AI vs user creates planning files #45

New issue

Closed

opened 2026-03-03 18:50:14 +03:00 by kerem · 1 comment

kerem commented

2026-03-03 18:50:14 +03:00

Owner

Originally created by @haimat on GitHub (Feb 4, 2026).
Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/69

Description

The documentation contradicts itself about whether the AI or the user should create the planning files (task_plan.md, findings.md, progress.md).

Contradicting sources

Location	Says
GitHub README	"Claude automatically creates the three files"
`docs/quickstart.md`	"Users must create the three planning files at the start"
`SKILL.md` (line 94-96)	"Create `task_plan.md` — Use templates as reference" (implies AI creates)
`examples.md`	Shows AI writing files in response to user requests

Impact

Users don't know if they should create files manually or wait for AI
AI doesn't know if it should ask for task description first or immediately create files
When invoking /planning-with-files without a task description, AI may incorrectly infer task from conversation context instead of asking the user what they want to plan

Suggested clarification

Add explicit workflow to SKILL.md and align all docs:

## Workflow

1. User invokes `/planning-with-files`
2. If no task description provided, AI asks: "What task would you like to plan?"
3. AI creates the three planning files based on user's task description
4. AI and user collaborate to update files throughout the task

Affected files

README.md
docs/quickstart.md
SKILL.md

Originally created by @haimat on GitHub (Feb 4, 2026). Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/69 ## Description The documentation contradicts itself about whether the AI or the user should create the planning files (`task_plan.md`, `findings.md`, `progress.md`). ## Contradicting sources | Location | Says | |----------|------| | GitHub README | "Claude **automatically creates** the three files" | | `docs/quickstart.md` | "**Users must create** the three planning files at the start" | | `SKILL.md` (line 94-96) | "**Create** `task_plan.md` — Use templates as reference" (implies AI creates) | | `examples.md` | Shows AI writing files in response to user requests | ## Impact 1. Users don't know if they should create files manually or wait for AI 2. AI doesn't know if it should ask for task description first or immediately create files 3. When invoking `/planning-with-files` without a task description, AI may incorrectly infer task from conversation context instead of asking the user what they want to plan ## Suggested clarification Add explicit workflow to `SKILL.md` and align all docs: ```markdown ## Workflow 1. User invokes `/planning-with-files` 2. If no task description provided, AI asks: "What task would you like to plan?" 3. AI creates the three planning files based on user's task description 4. AI and user collaborate to update files throughout the task ``` ## Affected files - README.md - docs/quickstart.md - SKILL.md

kerem closed this issue

2026-03-03 18:50:14 +03:00

kerem commented

2026-03-03 18:50:15 +03:00

Author

Owner

@OthmanAdi commented on GitHub (Feb 4, 2026):

Fixed in master — thanks @haimat for catching this!

The docs now consistently say: the AI creates the planning files after the user describes their task. If no task description is provided, the AI asks first.

Updated:

README.md — Clarified the Usage section workflow
docs/quickstart.md — Step 1 now says "Invoke the skill and describe your task" instead of "Create your planning files"

Manual creation via init-session.sh is still documented as an alternative.

@OthmanAdi commented on GitHub (Feb 4, 2026): Fixed in master — thanks @haimat for catching this! The docs now consistently say: the **AI creates the planning files** after the user describes their task. If no task description is provided, the AI asks first. Updated: - `README.md` — Clarified the Usage section workflow - `docs/quickstart.md` — Step 1 now says "Invoke the skill and describe your task" instead of "Create your planning files" Manual creation via `init-session.sh` is still documented as an alternative.

No labels

bug

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/planning-with-files#45

No description provided.

Rows
Columns