edit

Author: karaposu

commands/critic-d.md

@@ -52,16 +52,26 @@ Document:
 - Security considerations
 - Required refactoring before implementation
 - Performance implications (latency, memory, storage)
+- Question architectural choices for future development,deployment, propose better alternatives to the plan's approach if they match the project's and feature's fundementals. 
+- if any near future requirements are in your context regarding codebase, use them to show better alternative approaches too. But explicitylu state that they are better in the future context only. 
+- Don't just patch the plan — question whether the plan's assumptions are correct.
+
 
 Rate each risk (severity) as: Low/Medium/High
-For each Medium/High risk, suggest three levels of mitigation : a quick fix, a robust fix, and a long-term fix. and for robust fix add a subfield called  "why this is robust:" and for long term fix  add a subfield called  "why this is long term effective:"
+For each Medium/High risk, suggest three levels of mitigation : 
+    - a quick fix,
+    - a robust fix 
+    - a long-term fix. 
+   for robust fix add a subfield called  "why this is robust:" and for long term fix  add a subfield called  "why this is long term effective:"
+
 Each Item should have impact field (possible effects of this Risk Item ), ELI10 field (non technical explanaition),| NoobEng field(explaining like explaining to a noob for engineer who doesnt understand the underlying dynamics)
 
 Analyze how this feature will interact with the existing codebase:
 
 1. Read all relevant module interfaces and implementations
 2. Create critic.md in relevant devdocs folder (same folder as our step by step plan file )
 
+
 ----
 
 But this prompt is too generic — it doesn't account for the specifics of the current task.

commands/devdocs-archivist.md

@@ -0,0 +1,118 @@
+# /devdocs-archivist — DevDocs Archive Collector
+
+Scan all devdocs, compare each folder and file against the codebase and current context, and determine what should be archived. The archivist is conservative — it only archives work that is done, understanding documents that have already been consumed into plans, and alternative approaches that were not chosen.
+
+## Additional Input/Instructions
+
+$ARGUMENTS
+
+---
+
+## Instructions
+
+### Step 1: Scan
+
+Read every folder and file under `devdocs/`, excluding:
+- `devdocs/archive/` — already archived
+- `devdocs/*/future/` — planned work, never archive candidates
+- `devdocs/roadmaps/` — always active reference material
+- `devdocs/archaeology/` — always active (unless explicitly told to archive old traces)
+
+For each folder and file, build an understanding of:
+- What work or understanding does this document describe?
+- What is the current state of that work in the codebase?
+- Does any other active (non-archive) devdoc reference this document?
+
+### Step 2: Classify Each Item
+
+For each folder/file, determine one of three verdicts:
+
+**ARCHIVE** — The work described is done (reflected in the codebase) OR the document's understanding has been consumed into a plan/implementation and is no longer needed in active context.
+
+**KEEP** — The work is not done, OR the document contains knowledge still relevant to active work, OR another active document references it.
+
+**KEEP (reference hold)** — The work is done, but another active document references it. It stays until the referencing document is also ready to archive. Then both move together.
+
+### Step 3: Handle Edge Cases
+
+**Archive as a unit, not per-file.** When a folder's work is done, archive the ENTIRE folder — desc.md, plan, critic, sensemaking, all of it. They form a coherent unit of completed work and should stay together.
+
+**Exception — orphaned alternatives.** Sometimes multiple approaches are explored for the same work (e.g., two different sensemaking analyses, two plan versions). If only one was used and the others are alternatives for the SAME completed work, archive them together with the used one. However, if an unused alternative is actually a separate idea/enhancement that could still be relevant independently, it stays.
+
+**Cross-reference integrity.** Before archiving any item, check: does any ACTIVE (non-archive candidate) document reference it? If yes, the item stays until the referencing document is also an archive candidate.
+
+### Step 4: Determine Archive Paths
+
+Each archive run creates its own folder using a timestamp:
+
+```
+devdocs/archive/run_YYYY_MM_DD_HH_MM_SS/
+```
+
+Inside this run folder, each archived item gets a dated folder with its origin path:
+
+```
+devdocs/archive/run_2026_04_01_15_38_12/
+├── 2026-04-01_scoped_feat_12_auth/       ← was devdocs/scoped/feat_12_auth/
+├── 2026-04-01_ideas_scorer_model/        ← was devdocs/ideas/scorer_model/
+└── 2026-04-01_clarifications_oauth2/     ← was devdocs/clarifications/oauth2.md
+```
+
+The naming convention: `{date}_{origin_path_underscored}/`. This makes each archived item searchable by date and traceable back to where it came from. No collisions, fully recoverable.
+
+### Step 5: Execute or Document
+
+**Default behavior (no flags):** Present the full archive plan to the user — list every item with its verdict (ARCHIVE/KEEP), reasoning, and destination path. Ask for confirmation before moving anything.
+
+**With `-doc` flag:** Do NOT move any files. Instead, create a markdown report at `devdocs/archive_report_YYYY_MM_DD.md` documenting the full analysis:
+
+For each folder/file in devdocs:
+
+```markdown
+### devdocs/scoped/feat_12_auth/
+
+**Verdict:** ARCHIVE
+**Reason:** All described changes are reflected in the codebase. Auth token refresh, session management, and OAuth2 integration are implemented and tested. No active documents reference this folder.
+**Archive path:** devdocs/archive/run_2026_04_01_15_38_12/2026-04-01_scoped_feat_12_auth/
+
+---
+
+### devdocs/ideas/event_driven_architecture/
+
+**Verdict:** KEEP
+**Reason:** The exploration is ongoing. No implementation exists in the codebase. The sensemaking analysis is still being referenced by devdocs/roadmaps/system_redesign/map.md.
+
+---
+
+### devdocs/clarifications/oauth2_grant_types.md
+
+**Verdict:** ARCHIVE
+**Reason:** This understanding was consumed into devdocs/scoped/feat_12_auth/desc.md and step_by_step_impl_plan.md. The auth feature is complete. No other active document references this clarification.
+**Archive path:** devdocs/archive/run_2026_04_01_15_38_12/2026-04-01_clarifications_oauth2_grant_types/
+```
+
+---
+
+## Rules
+
+1. **Staleness is inferred, not declared.** Check the codebase — "does the code reflect what this doc describes?" Do NOT rely on manual status fields or metadata tags.
+
+2. **Archive as a unit.** When a folder's work is done, move the entire folder. Don't cherry-pick files from inside a folder unless they are genuinely unrelated to the folder's main work.
+
+3. **Cross-references block archiving.** If an active doc references a done doc, the done doc stays. Both move together when both are ready.
+
+4. **Be conservative.** When uncertain whether work is truly done, verdict is KEEP. False negatives (keeping something stale) are better than false positives (archiving something still needed).
+
+5. **Never touch future/.** Items in any `future/` subfolder are planned work and are never archive candidates.
+
+6. **Never touch roadmaps/ or archaeology/.** These are always-active reference material. Only archive old archaeology traces if explicitly told to.
+
+7. **Each run is isolated.** Every archive execution creates a new `run_YYYY_MM_DD_HH_MM_SS/` folder. This means multiple runs don't collide, and each run is a recoverable unit — you can undo an entire run by moving its folder back.
+
+---
+
+## Output
+
+**Without `-doc`:** Print the archive plan in the conversation. For each item: verdict, reasoning, archive path. Ask for confirmation, then move files.
+
+**With `-doc`:** Create `devdocs/archive_report_YYYY_MM_DD.md` with the full analysis. Do NOT move any files. Print a summary in the conversation (how many items analyzed, how many ARCHIVE, how many KEEP, how many reference-held).

commands/install.sh

@@ -30,6 +30,7 @@ commands=(
   dead-code-concepts.md
   roadmap.md
   overview-report.md
+  devdocs-archivist.md
 )
 
 for cmd in "${commands[@]}"; do
@@ -58,7 +59,7 @@ echo ""
 echo "Done. Installed ${#commands[@]} slash commands to $COMMANDS_DIR"
 echo "Done. Installed ${#hooks[@]} hooks to $HOOKS_DIR"
 echo ""
-echo "Slash commands: /elaborate, /task-desc, /task-plan, /critic, /critic-d, /sense-making, /arch-small-summary, /arch-intro, /arch-traces, /arch-top-improvements, /dead-code-index, /dead-code-concepts, /roadmap, /overview-report"
+echo "Slash commands: /elaborate, /task-desc, /task-plan, /critic, /critic-d, /sense-making, /arch-small-summary, /arch-intro, /arch-traces, /arch-top-improvements, /dead-code-index, /dead-code-concepts, /roadmap, /overview-report, /devdocs-archivist"
 echo ""
 echo "To activate the devdocs metadata hook, add this to .claude/settings.json:"
 echo ""

commands/overview-report.md

@@ -36,10 +36,10 @@ Collect information from these sources for the given period:
 actually inspecting what changed in each modified file, No just reported on things you already have context.. your context is not full.     RUN and an actual investigation of the diff. The right process is to git diff HEAD -- <file> for every file in the stat output and document what each change ...                                                                                     
 
 **Devdocs artifacts** — scan `devdocs/` for files created or modified within the period:
-- `devdocs/enhancements/` — any step_by_step_plan.md, desc.md, critic.md files
+- `devdocs/scoped/` — any step_by_step_plan.md, desc.md, critic.md files
 - `devdocs/archaeology/` — traces, summaries, dead code indexes
 - `devdocs/roadmaps/` — any roadmap activity
-- `devdocs/fixes/` — any fix documentation
+- `devdocs/ideas/` — any fix documentation
 - Any other devdocs subfolders that have recent activity
 
 **Conversation context** — if relevant context from recent conversation is available, incorporate it.

commands/smart-debug.md

@@ -0,0 +1,7 @@
+
+
+okay we need a better structured understanding of current system in order to catch the main issue. And the way to do that is track the full process using logs. However a blind tracking and designating one issue and focusing on that is not enough. Becase spotted anamoly might be the reason of bigger error in the code. 
+
+First divide this operation which is not working properly (due to bug or wrong data etc) into the main steges. And for each stage identify relevant variables and logs that would validate things are okay or not.  
+
+then use the existing logs as well as structlog logs to compare and find at which stage error is coming from

commands/task-plan.md

@@ -1,57 +1,86 @@
-# /task-plan — Generate Step-by-Step Implementation Plan
+# /task-plan — (Two-Phase)
 
-Generate a detailed implementation plan for the feature described in the input. This plan becomes the single source of truth for execution.
+Generate a step a step implementation plan for given task desc 
 
 ## Additional Input/Instructions
 
-
 $ARGUMENTS
 
 ## Instructions
 
-### Step 0: Resolve Which Feature to Plan
+### Phase 0: Resolve Which task desc to base the implemenation plan (if it is not stated clearly and explicitly)
+
+unless it is not clearly stated do this :
+Use your understanding of the already developed context or given Additional Input/Instructions (can be about codebase workspace, or past conversation regarding this topic etc) to interpret what is the relevant desc markdown file,
+ 
+If multiple descs/tasks are referred in past recent messages (check last 4,5 messages)  — present them as a numbered list and ask the user to confirm which one to create the implement the plan . Do NOT proceed until the user confirms.
+
+**If only one task/desc exists** — show the user which plan you found and ask for a quick confirmation before proceeding.
+
+
 
-Before generating anything, determine which feature description this plan is based on:
 
-1. **If the input is a file path** — use that directly.
-2. **If the input is ambiguous or empty** — look at the project's existing `devdocs/` folder structure and scan for `desc.md` files. List every feature found with its name and path.
-3. **If multiple features exist** — present them as a numbered list and ask the user to confirm which one to plan for. Do NOT proceed until the user confirms.
-4. **If only one feature exists** — show the user which feature you found and ask for a quick confirmation before proceeding.
 
-**Only after the user confirms**, continue to Step 1.
 
-### Step 1: Read and Analyze
 
-1. Read the confirmed `desc.md` file (or input) fully.
-2. Thoroughly read all relevant code files in the codebase to understand:
-   - Existing patterns and conventions
-   - Module interfaces and dependencies
-   - Where the new code will live
-   - What existing code will be touched
-3. Think deeply before writing. Use extended thinking to reason through the implementation.
-4. Create a `step_by_step_plan.md` in the same directory as the `desc.md` (no plan mode, i just need the .md).
+Phase 1:
+Understand the given task desc in detail. Understand what it tries to achieve by not just code but also using project context, or any bug/fix context as well. 
 
-## Output Format
+First think and understand all the steps that need to be done. Once it is clear and in harmony. 
 
-The `step_by_step_plan.md` must contain:
+Start creating step_by_step_impl_plan.md in same folder in such way:
 
+
+## Top-Level Structure
+Start the plan with these sections before any steps:
+
+### What is the task
+One paragraph explaining WHAT we're trying to achieve and WHY.
+Not the steps — the intent.
+
+### How this implementation moves toward desired state
+Explain how the series of changes transforms the current state
+into the desired state. The bridge between the problem (desc.md)
+and the solution (steps).
 ### High-Level Summary
-Bullet-point overview of the implementation approach (5-10 bullets max). Someone should be able to read just this section and understand the plan.
 
-### Full Implementation Plan
-For each step:
-- **Step N: [Title]**
-  - What to do (specific files, functions, changes)
-  - Why (rationale for this approach)
-  - Dependencies (what must exist before this step)
-  - Acceptance criteria (how to verify this step is done)
+A table with one row per step — step number, short description,
+and expected output. The reader should understand the full shape
+of the plan in 30 seconds.
+| Step | Description | Expected Output |
+|------|-------------|-----------------|
+| 1    | ...         | ...             |
+---
+
+## Per-Step Structure
+
+Each step has:
+
+### Proposed changes
+
+Freestyle explanation of what this step does. Can be long or
+short depending on complexity. Include file paths and code
+snippets where helpful.
+
+### Output
+
+What concretely exists after this step that didn't before.
+A new file, a changed column, a wired connection. Specific
+and verifiable.
+
+### Safe in nature
+True or False. True means this step cannot break existing
+functionality. False means it touches existing behavior and
+requires care.
+
+### Peripheral concepts
+What other concepts in the codebase this change touches.
+Listed inline, not one per line.
+Example: async_sessionmaker, Storage facade, tool closures, session lifecycle
+
 
-### Files to Modify/Create
-List every file that will be touched, with a one-line description of the change.
+### Hardness Lvl
+1 to 5. Sets expectations for complexity and review attention.
 
-## Guidelines
 
-- Be specific. "Update the API" is useless. "Add `POST /api/features` endpoint in `src/routes/features.ts`" is useful.
-- Follow existing codebase conventions — don't introduce new patterns unless necessary.
-- Order steps so each builds on the previous. No circular dependencies.
-- Keep the plan implementable in a single session where possible. If it's too large, note where to split.
+Create step_by_step_impl_plan.md in relevant devdocs folder (same folder as our desc files, probably under devdocs/scoped but it can be in other folders too )

commands/task-plan_old.md

@@ -0,0 +1,57 @@
+# /task-plan — Generate Step-by-Step Implementation Plan
+
+Generate a detailed implementation plan for the feature described in the input. This plan becomes the single source of truth for execution.
+
+## Additional Input/Instructions
+
+
+$ARGUMENTS
+
+## Instructions
+
+### Step 0: Resolve Which Feature to Plan
+
+Before generating anything, determine which feature description this plan is based on:
+
+1. **If the input is a file path** — use that directly.
+2. **If the input is ambiguous or empty** — look at the project's existing `devdocs/` folder structure and scan for `desc.md` files. List every feature found with its name and path.
+3. **If multiple features exist** — present them as a numbered list and ask the user to confirm which one to plan for. Do NOT proceed until the user confirms.
+4. **If only one feature exists** — show the user which feature you found and ask for a quick confirmation before proceeding.
+
+**Only after the user confirms**, continue to Step 1.
+
+### Step 1: Read and Analyze
+
+1. Read the confirmed `desc.md` file (or input) fully.
+2. Thoroughly read all relevant code files in the codebase to understand:
+   - Existing patterns and conventions
+   - Module interfaces and dependencies
+   - Where the new code will live
+   - What existing code will be touched
+3. Think deeply before writing. Use extended thinking to reason through the implementation.
+4. Create a `step_by_step_plan.md` in the same directory as the `desc.md` (no plan mode, i just need the .md).
+
+## Output Format
+
+The `step_by_step_plan.md` must contain:
+
+### High-Level Summary
+Bullet-point overview of the implementation approach (5-10 bullets max). Someone should be able to read just this section and understand the plan.
+
+### Full Implementation Plan
+For each step:
+- **Step N: [Title]**
+  - What to do (specific files, functions, changes)
+  - Why (rationale for this approach)
+  - Dependencies (what must exist before this step)
+  - Acceptance criteria (how to verify this step is done)
+
+### Files to Modify/Create
+List every file that will be touched, with a one-line description of the change.
+
+## Guidelines
+
+- Be specific. "Update the API" is useless. "Add `POST /api/features` endpoint in `src/routes/features.ts`" is useful.
+- Follow existing codebase conventions — don't introduce new patterns unless necessary.
+- Order steps so each builds on the previous. No circular dependencies.
+- Keep the plan implementable in a single session where possible. If it's too large, note where to split.