Skip to content

Commit d69578d

Browse files
karaposukaraposu
committed
edit
1 parent 7be1242 commit d69578d

9 files changed

Lines changed: 100 additions & 45 deletions

‎commands/arch-intro.md‎

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Read the codebase and produce an architecture introduction as if you're onboarding a new engineer. Focus on how things are designed, not what features exist.
44

5-
## Input
5+
## Additional Input/Instructions
66

77
$ARGUMENTS
88

@@ -21,16 +21,7 @@ $ARGUMENTS
2121

2222
### Output
2323

24-
**If `--save` is passed as an argument:**
25-
- Write the introduction to `devdocs/archaeology/intro2codebase.md` (create the directory if needed).
26-
- If that file already exists, overwrite it completely — rewrite fresh, don't patch.
24+
By default, save the introduction to `devdocs/archaeology/intro2codebase.md` (create the directory if needed) and print it in the conversation.
25+
If that file already exists, overwrite it completely — rewrite fresh, don't patch.
2726

28-
**Otherwise:**
29-
- Print the introduction directly in the conversation only.
30-
31-
### Examples
32-
33-
```
34-
/arch-intro → prints intro in conversation
35-
/arch-intro --save → prints + saves to devdocs/archaeology/intro2codebase.md
36-
```
27+
**If `-n` is passed:** print in conversation only, don't write a file.

‎commands/arch-small-summary.md‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22

33
Read all code files in the project and produce a non-technical summary of what this project is and does — based purely on what the code shows, not what documentation claims.
44

5-
## Input
5+
## Additional Input/Instructions
66

77
$ARGUMENTS
88

9+
---
10+
911
## Instructions
1012

1113
1. Read all code files in the codebase fully. Focus on source code — ignore existing documentation, READMEs, and comments that describe intent rather than behavior.
@@ -23,16 +25,7 @@ $ARGUMENTS
2325

2426
### Output
2527

26-
**If `--save` is passed as an argument:**
27-
- Write the summary to `devdocs/archaeology/small_summary.md` (create the directory if needed).
28-
- If that file already exists, overwrite it completely — do not append or patch, rewrite the whole thing fresh.
29-
30-
**Otherwise:**
31-
- Print the summary directly in the conversation only.
32-
33-
### Examples
28+
By default, save the summary to `devdocs/archaeology/small_summary.md` (create the directory if needed) and print it in the conversation.
29+
If that file already exists, overwrite it completely — do not append or patch, rewrite the whole thing fresh.
3430

35-
```
36-
/arch-small-summary → prints summary in conversation
37-
/arch-small-summary --save → prints + saves to devdocs/archaeology/small_summary.md
38-
```
31+
**If `-n` is passed:** print in conversation only, don't write a file.

‎commands/arch-top-improvements.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22

33
Based on all existing traces, identify the 5 highest-impact improvements for this codebase — the changes that would make the biggest difference to quality, stability, or maintainability.
44

5-
## Input
5+
## Additional Input/Instructions
66

77
$ARGUMENTS
88

9+
---
10+
911
## Instructions
1012

1113
1. Read all trace files under `devdocs/archaeology/traces/`. If no traces exist, tell the user to run `/arch-traces` first.

‎commands/arch-traces.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# /arch-traces — End-to-End Interaction Traces
22

3-
To run traces the context should already have enough level of the understanding of the codebase. If codebase is structure is unknown output "to run traces run arch-summary and arch-intro first"
3+
## Additional Input/Instructions
4+
5+
$ARGUMENTS
6+
7+
---
8+
9+
To run traces the context should already have enough level of the understanding of the codebase. If codebase structure is unknown output "to run traces run arch-summary and arch-intro first"
410

511
Identify every internal interface and submodule-level interaction defined within the codebase (excluding external packages). For each interface, follow its execution path end-to-end: what calls it, what it triggers, how data or state moves through the layers, and what outcomes it produces.
612

‎commands/sense-making.md‎

Lines changed: 56 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,21 @@
22

33
Analyze the given input using the Structural Sensemaking Framework. This transforms vague, ambiguous, or complex input into stable, clear understanding through systematic anchor extraction, perspective checking, ambiguity collapse, and constraint reduction.
44

5-
## Input
5+
## Additional Input/Instructions
66

77
$ARGUMENTS
88

9-
## Instructions
9+
---
1010

11-
1. Parse the input. It can be:
12-
- **Raw text only** — a task description, idea, problem statement, or any unstructured input.
13-
- **A file path only** — read the file and use its contents as the input.
14-
- **A file path + additional text** — read the file first, then treat the remaining text as extra context on top of the file contents. Both parts matter.
11+
## Instructions
1512

16-
If the input starts with something that looks like a file path (e.g. `devdocs/...`, `src/...`, or any path with `/`), attempt to read it as a file. Everything after the path is additional context.
13+
1. Read the input and consume it. It can be raw text, It can be folder path with md files, code files or image path. Consume all input.
1714

1815
2. Use codebase context where relevant to ground the analysis in concrete reality.
1916

2017
3. Execute the full Structural Sensemaking process described below, producing all Sense Versions (SV1 through SV6).
2118

22-
4. Save the output as a markdown file:
19+
4. Save the output as a markdown file (unless differently stated in additional instructions!):
2320
- **If the input was a file path** — save in the same folder as the input file.
2421
- **Otherwise** — save under `devdocs/sensemaking/<suitable-name>.md` (create the directory if needed).
2522

@@ -84,6 +81,56 @@ A conceptual structure is the stabilized result of anchor interaction and bounda
8481

8582
---
8683

84+
85+
## Process Model
86+
87+
Structural Sensemaking proceeds through five iterative phases:
88+
89+
### Phase 1 — Signal Detection
90+
91+
* Recognition of a vague but meaningful pattern
92+
* Pre-verbal intuition of relevance
93+
94+
### Phase 2 — Anchor Extraction
95+
96+
* Identification of initial anchors
97+
* Documentation of constraints, insights, and principles
98+
99+
### Phase 3 — Perspective Expansion
100+
101+
* Deliberate exploration of alternative viewpoints
102+
* Generation of additional anchors
103+
104+
### Phase 4 — Boundary Formation
105+
106+
* Collapsing ambiguities
107+
* Resolving conflicts
108+
* Reducing degrees of freedom
109+
110+
### Phase 5 — Conceptual Stabilization
111+
112+
* Integration of surviving anchors
113+
* Formation of a coherent model
114+
* Articulation of understanding
115+
116+
The process is iterative and recursive rather than strictly linear.
117+
118+
---
119+
120+
## Standard Analysis Protocol
121+
122+
When applying Structural Sensemaking to a task:
123+
124+
1. Define the problem or situation
125+
2. Extract cognitive anchors
126+
3. Perform perspective checking
127+
4. Collapse ambiguities
128+
5. Reduce degrees of freedom
129+
6. Synthesize a stable conceptual model
130+
131+
132+
---- NOW SOLID INSTRUCTIONS START----
133+
87134
## Execute the Following Process
88135

89136
### Initial Sense Version (SV1 — Baseline Understanding)
@@ -196,4 +243,4 @@ Synthesize results into:
196243

197244
Present the final, high-level conceptual model. This should represent mature, low-ambiguity understanding.
198245

199-
Explain how it differs from SV1.
246+
Explain how it differs from SV1.

‎commands/task-desc.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@
22

33
Generate a structured feature description document based on the input below. This creates the foundational documentation that all subsequent planning builds on.
44

5-
## Input
5+
## Additional Input/Instructions
6+
67

78
$ARGUMENTS
89

10+
---
11+
912
## Instructions
1013

1114
### Step 0: Resolve Target Location

‎commands/task-plan.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
Generate a detailed implementation plan for the feature described in the input. This plan becomes the single source of truth for execution.
44

5-
## Input
5+
## Additional Input/Instructions
6+
67

78
$ARGUMENTS
89

‎issue.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
and i have a question which should be tackled in detailed way later on. for now i am just focused on defining the question
2+
better, \
3+
4+
5+
6+
devdocs is good, but different branches has different code and for example traces should be differ per branch or not?
7+
8+
or when should we update the devdocs? who? how we will know they are uptodate?
9+
10+
one feature implementation can spread into multiple brnahces then what?
11+
12+
should we have process of merging devdocs (via LLMs) as well? would that solve issues?

‎src/APPENDIX8_Alignstack_Slash_Commands.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -146,8 +146,8 @@ These commands are for understanding existing codebases. They read code (not doc
146146

147147
Read all code files and produce a non-technical summary of the project — what it does, what state it's in, who would use it. Based purely on code behavior, not what docs claim.
148148

149-
**Input**: Optional `--save` flag
150-
**Output**: Prints in conversation. With `--save`, also writes to `devdocs/archaeology/small_summary.md`
149+
**Input**: Optional `-n` flag (no save)
150+
**Output**: Saves to `devdocs/archaeology/small_summary.md` + prints in conversation
151151

152152
[View full command](../commands/arch-small-summary.md)
153153

@@ -157,8 +157,8 @@ Read all code files and produce a non-technical summary of the project — what
157157

158158
Produce a high-level architecture introduction covering data flow paths, main abstractions, and top-level design patterns. Written as if onboarding a new engineer on their first day.
159159

160-
**Input**: Optional `--save` flag
161-
**Output**: Prints in conversation. With `--save`, also writes to `devdocs/archaeology/intro2codebase.md`
160+
**Input**: Optional `-n` flag (no save)
161+
**Output**: Saves to `devdocs/archaeology/intro2codebase.md` + prints in conversation
162162

163163
[View full command](../commands/arch-intro.md)
164164

@@ -198,8 +198,8 @@ Requires `/arch-traces` to have been run first.
198198
| `/critic` | Risk/error/conflict analysis (generic) | `critic.md` |
199199
| `/critic-d` | Risk analysis (dynamic, two-phase) | `dynamic_critic_prompt.md` + `critic.md` |
200200
| `/sense-making` | Structural sensemaking analysis | Markdown file(s) |
201-
| `/arch-small-summary` | Non-technical project summary | Conversation or `devdocs/archaeology/small_summary.md` |
202-
| `/arch-intro` | Architecture introduction | Conversation or `devdocs/archaeology/intro2codebase.md` |
201+
| `/arch-small-summary` | Non-technical project summary | `devdocs/archaeology/small_summary.md` + conversation |
202+
| `/arch-intro` | Architecture introduction | `devdocs/archaeology/intro2codebase.md` + conversation |
203203
| `/arch-traces` | End-to-end interaction traces | `devdocs/archaeology/traces/` |
204204
| `/arch-top-improvements` | 5 highest-impact improvements | `devdocs/archaeology/top_improvements.md` |
205205

0 commit comments

Comments
 (0)