@rse/ase 0.9.2 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dst/ase-hello.js +24 -0
- package/dst/ase-statusline.js +15 -5
- package/package.json +2 -2
- package/plugin/.claude-plugin/plugin.json +1 -1
- package/plugin/.github/plugin/plugin.json +1 -1
- package/plugin/agents/ase-meta-review.md +188 -0
- package/plugin/etc/eslint.mjs +25 -0
- package/plugin/etc/markdownlint.yaml +13 -11
- package/plugin/etc/stx.conf +2 -1
- package/plugin/meta/ase-control.md +7 -2
- package/plugin/meta/ase-dialog.md +2 -0
- package/plugin/meta/ase-format-arch.md +31 -31
- package/plugin/meta/ase-format-spec.md +3 -3
- package/plugin/meta/ase-getopt.md +1 -0
- package/plugin/meta/ase-persona.md +1 -1
- package/plugin/meta/ase-skill.md +6 -6
- package/plugin/package.json +5 -2
- package/plugin/skills/ase-arch-analyze/SKILL.md +33 -33
- package/plugin/skills/ase-code-lint/SKILL.md +1 -1
- package/plugin/skills/ase-code-lint/help.md +1 -1
- package/plugin/skills/ase-docs-distill/SKILL.md +158 -0
- package/plugin/skills/ase-docs-distill/help.md +76 -0
- package/plugin/skills/ase-docs-proofread/SKILL.md +1 -1
- package/plugin/skills/ase-docs-proofread/help.md +1 -1
- package/plugin/skills/ase-meta-brainstorm/SKILL.md +17 -11
- package/plugin/skills/ase-meta-brainstorm/help.md +4 -4
- package/plugin/skills/ase-meta-diaboli/SKILL.md +4 -4
- package/plugin/skills/ase-meta-diaboli/help.md +2 -2
- package/plugin/skills/ase-meta-diff/SKILL.md +110 -64
- package/plugin/skills/ase-meta-diff/help.md +30 -6
- package/plugin/skills/ase-meta-review/SKILL.md +166 -0
- package/plugin/skills/ase-meta-review/help.md +70 -0
- package/plugin/skills/ase-meta-steelman/SKILL.md +159 -0
- package/plugin/skills/ase-meta-steelman/help.md +60 -0
- package/plugin/skills/ase-meta-why/help.md +1 -1
- package/plugin/skills/ase-task-condense/SKILL.md +3 -3
- package/plugin/skills/ase-task-implement/help.md +1 -1
|
@@ -122,46 +122,46 @@ interface quality, quality attributes, and architecture governance.
|
|
|
122
122
|
task into appropriate chunks.
|
|
123
123
|
|
|
124
124
|
*Determine* the *target programming language* and the *declared
|
|
125
|
-
architecture style* (if any)
|
|
125
|
+
architecture style* (if any) - e.g., Layered, Hexagonal
|
|
126
126
|
(Ports & Adapters), Onion, Clean, CQRS, Microservices,
|
|
127
|
-
Event-Driven, Modular Monolith
|
|
127
|
+
Event-Driven, Modular Monolith - from code, project documentation,
|
|
128
128
|
README files, or folder structure.
|
|
129
129
|
|
|
130
130
|
Investigate the following architecture quality aspects across
|
|
131
131
|
7 thematic blocks:
|
|
132
132
|
|
|
133
|
-
**Block 1
|
|
133
|
+
**Block 1 - Component Boundaries**:
|
|
134
134
|
|
|
135
135
|
- **SA01 COMPONENT-RESPONSIBILITY**: each component (module,
|
|
136
|
-
class, package) addresses exactly *one single concern*
|
|
136
|
+
class, package) addresses exactly *one single concern* -
|
|
137
137
|
i.e., has exactly *one reason to change*.
|
|
138
138
|
- **SA02 COMPONENT-GRANULARITY**: components have *appropriate
|
|
139
|
-
size*
|
|
139
|
+
size* - neither monolithic nor fragmented.
|
|
140
140
|
- **SA03 COMPONENT-HIERARCHY**: components placed at the *correct
|
|
141
141
|
level* of the component hierarchy (system / program / module /
|
|
142
142
|
class / function).
|
|
143
143
|
|
|
144
|
-
**Block 2
|
|
144
|
+
**Block 2 - Structural Organization**:
|
|
145
145
|
|
|
146
146
|
- **SA04 LAYERING**: *layers* (horizontal cuts) clearly
|
|
147
147
|
separated, named, and ranked; no upward dependencies.
|
|
148
|
-
- **SA05 SLICING**: *slices* (vertical cuts
|
|
148
|
+
- **SA05 SLICING**: *slices* (vertical cuts - e.g., feature
|
|
149
149
|
modules, bounded contexts) clearly separated and *cycle-free*.
|
|
150
150
|
- **SA06 DEPENDENCY-DIRECTION**: dependencies flow in exactly
|
|
151
151
|
*one direction*; no *circular dependencies*.
|
|
152
|
-
- **SA07 REFERENCE-ARCHITECTURE**: *declared-style conformance*
|
|
152
|
+
- **SA07 REFERENCE-ARCHITECTURE**: *declared-style conformance* -
|
|
153
153
|
the chosen architecture style (see STEP 1 intro for the
|
|
154
154
|
recognized style list) is applied *consistently* throughout
|
|
155
155
|
the codebase, without accidental mixing of styles.
|
|
156
156
|
|
|
157
|
-
**Block 3
|
|
157
|
+
**Block 3 - Architecture Principles**:
|
|
158
158
|
|
|
159
|
-
- **SA08 COUPLING**: *loose data coupling* between components
|
|
159
|
+
- **SA08 COUPLING**: *loose data coupling* between components -
|
|
160
160
|
no *concrete-type dependencies* where abstractions exist, no
|
|
161
161
|
shared data structures leaking across boundaries, communication
|
|
162
162
|
via defined ports / facades / DTOs. (Runtime coupling such as
|
|
163
163
|
races and shared mutable state is covered by SA17.)
|
|
164
|
-
- **SA09 COHESION**: *strong cohesion* within each component
|
|
164
|
+
- **SA09 COHESION**: *strong cohesion* within each component -
|
|
165
165
|
internal parts (functions, fields, methods) are *tightly
|
|
166
166
|
related*, *co-change*, and share data or behavior; scattered
|
|
167
167
|
helpers that merely coexist by accident are flagged.
|
|
@@ -175,7 +175,7 @@ interface quality, quality attributes, and architecture governance.
|
|
|
175
175
|
behind a simple interface that *shields* its implementation
|
|
176
176
|
details.
|
|
177
177
|
|
|
178
|
-
**Block 4
|
|
178
|
+
**Block 4 - Interface Quality**:
|
|
179
179
|
|
|
180
180
|
- **SA13 INTERFACE-SIZE**: each interface *proportional in size*
|
|
181
181
|
to its functionality.
|
|
@@ -186,20 +186,20 @@ interface quality, quality attributes, and architecture governance.
|
|
|
186
186
|
*syntactic* and *semantic* contracts (pre/post-conditions,
|
|
187
187
|
invariants, idempotency, thread-safety).
|
|
188
188
|
|
|
189
|
-
**Block 5
|
|
189
|
+
**Block 5 - Quality Attributes**:
|
|
190
190
|
|
|
191
191
|
- **SA16 TESTABILITY**: architectural *seams* enable testing in
|
|
192
|
-
isolation
|
|
192
|
+
isolation - dependency injection at component boundaries,
|
|
193
193
|
mockable interfaces, side effects (DB, filesystem, network,
|
|
194
194
|
time, randomness) hidden behind abstractions.
|
|
195
195
|
- **SA17 CONCURRENCY**: the *concurrency model* (event loop,
|
|
196
196
|
threads, goroutines, async/await, actors, ...) is *explicitly
|
|
197
|
-
chosen* and applied *consistently*. *Runtime coupling*
|
|
197
|
+
chosen* and applied *consistently*. *Runtime coupling* -
|
|
198
198
|
thread-safety boundaries, shared mutable state, races, lock
|
|
199
|
-
hold times, async/sync boundaries
|
|
199
|
+
hold times, async/sync boundaries - is explicit and localized;
|
|
200
200
|
shared mutable state is protected.
|
|
201
201
|
|
|
202
|
-
**Block 6
|
|
202
|
+
**Block 6 - Architecture Governance**:
|
|
203
203
|
|
|
204
204
|
- **SA18 DECISION-RECORDS**: non-trivial architectural decisions
|
|
205
205
|
are *documented* with rationale (Architecture Decision Records
|
|
@@ -207,10 +207,10 @@ interface quality, quality attributes, and architecture governance.
|
|
|
207
207
|
The chosen style, deviations from defaults, and trade-offs are
|
|
208
208
|
traceable.
|
|
209
209
|
|
|
210
|
-
**Block 7
|
|
210
|
+
**Block 7 - Package Cohesion**:
|
|
211
211
|
|
|
212
212
|
- **SA19 PACKAGE-COHESION**: each first-party package has a
|
|
213
|
-
coherent role *and* topical theme
|
|
213
|
+
coherent role *and* topical theme - its members serve a
|
|
214
214
|
common purpose, share a dominant noun-cluster, and have
|
|
215
215
|
non-trivial cross-package use. Flag:
|
|
216
216
|
- *grab-bag*: members split into ≥3 unrelated topical
|
|
@@ -223,16 +223,16 @@ interface quality, quality attributes, and architecture governance.
|
|
|
223
223
|
overlap with the package's dominant noun-cluster, or with
|
|
224
224
|
its `package-info` / `README` declaration when present
|
|
225
225
|
- **SA20 PACKAGE-CYCLE**: no *cyclic dependencies* between
|
|
226
|
-
first-party packages
|
|
226
|
+
first-party packages - neither direct (`A → B` and `B → A`)
|
|
227
227
|
nor transitive (via *Tarjan SCC* or pairwise scan). Each
|
|
228
228
|
cycle is reported with the exact import lines that close it.
|
|
229
229
|
- **SA21 PACKAGE-SIZE**: package size and coupling shape are
|
|
230
|
-
justified
|
|
231
|
-
- *god-package*: *incoming ≥ 5* and *outgoing ≥ 3*
|
|
230
|
+
justified - flag packages at either extreme:
|
|
231
|
+
- *god-package*: *incoming ≥ 5* and *outgoing ≥ 3* -
|
|
232
232
|
coordinator dumping ground that should be split along its
|
|
233
233
|
internal topical clusters
|
|
234
234
|
- *fragment*: 1–2 files under a sibling parent that share a
|
|
235
|
-
*name prefix* or *imported interface* with that sibling
|
|
235
|
+
*name prefix* or *imported interface* with that sibling -
|
|
236
236
|
consolidation candidate
|
|
237
237
|
|
|
238
238
|
Hints:
|
|
@@ -253,7 +253,7 @@ interface quality, quality attributes, and architecture governance.
|
|
|
253
253
|
any claim about *ordering*, *lock hold time*, *thread
|
|
254
254
|
boundary*, or *call from context X*, trace the actual
|
|
255
255
|
acquire/release and call order line-by-line. Do not
|
|
256
|
-
pattern-match on "loop inside method with lock"
|
|
256
|
+
pattern-match on "loop inside method with lock" - verify
|
|
257
257
|
which operations sit *between* the specific acquire and
|
|
258
258
|
release in source order.
|
|
259
259
|
|
|
@@ -264,7 +264,7 @@ interface quality, quality attributes, and architecture governance.
|
|
|
264
264
|
incoming/outgoing class-edge map (drives SA20, SA21) and
|
|
265
265
|
the per-package noun-token frequency table extracted from
|
|
266
266
|
class names in camelCase / snake_case (drives SA19 topical
|
|
267
|
-
analysis). No external NLP
|
|
267
|
+
analysis). No external NLP - pure tokens. Cite each finding
|
|
268
268
|
with the exact import lines or class-name evidence.
|
|
269
269
|
|
|
270
270
|
- *Block 7 severity ladder*: SA20 (cycle) → HIGH; SA21
|
|
@@ -308,11 +308,11 @@ interface quality, quality attributes, and architecture governance.
|
|
|
308
308
|
Because `!` and `?` are Mermaid special characters, *always
|
|
309
309
|
quote* anomaly-bearing node labels:
|
|
310
310
|
|
|
311
|
-
- *Problem node*
|
|
311
|
+
- *Problem node* - prefix label with `!` inside quotes:
|
|
312
312
|
`A["!ComponentA"]`.
|
|
313
|
-
- *Unclear node*
|
|
313
|
+
- *Unclear node* - suffix label with `(?)` inside quotes:
|
|
314
314
|
`B["ComponentB (?)"]`.
|
|
315
|
-
- *Cyclic edge*
|
|
315
|
+
- *Cyclic edge* - annotate the *edge* (not a node) with a
|
|
316
316
|
`cycle` label on a bidirectional arrow:
|
|
317
317
|
`A <-- "cycle" --> B` (or two labelled one-way edges if
|
|
318
318
|
the renderer rejects `<-->`).
|
|
@@ -325,11 +325,11 @@ interface quality, quality attributes, and architecture governance.
|
|
|
325
325
|
Before reporting, classify every finding into one of three
|
|
326
326
|
categories:
|
|
327
327
|
|
|
328
|
-
- *Unpaired*
|
|
328
|
+
- *Unpaired* - single aspect violated, no partner in the
|
|
329
329
|
tension matrix hit → emit `PROBLEM` template.
|
|
330
|
-
- *Paired*
|
|
330
|
+
- *Paired* - exactly two aspects of a single tension pair hit
|
|
331
331
|
→ emit `TRADEOFF` template (cluster of size 2).
|
|
332
|
-
- *Clustered*
|
|
332
|
+
- *Clustered* - an aspect appears in *multiple* triggered
|
|
333
333
|
tensions (e.g., SA10 hit against both SA12 and SA13) →
|
|
334
334
|
collapse into *one* `TRADEOFF` with the recurring aspect
|
|
335
335
|
as *focal aspect* and the others as *partners*. One
|
|
@@ -367,7 +367,7 @@ interface quality, quality attributes, and architecture governance.
|
|
|
367
367
|
<template>
|
|
368
368
|
<ase-tpl-bullet-normal/> **TRADEOFF** T<n/> (Severity: <severity/>): **<title/>**
|
|
369
369
|
|
|
370
|
-
- *Focal aspect*: <focal-aspect/>
|
|
370
|
+
- *Focal aspect*: <focal-aspect/> - <focal-state/>
|
|
371
371
|
- *In tension with*: <partner-list/>
|
|
372
372
|
|
|
373
373
|
**RECOMMENDED**: lean toward *<focal|partners/>*
|
|
@@ -396,7 +396,7 @@ interface quality, quality attributes, and architecture governance.
|
|
|
396
396
|
(<description/>, <focal-state/>, partner-implications)
|
|
397
397
|
are *very brief* but *precise*. <rationale/> is exactly
|
|
398
398
|
*one sentence* grounded in the detected style, domain
|
|
399
|
-
constraints, or language idioms
|
|
399
|
+
constraints, or language idioms - never generic
|
|
400
400
|
principles.
|
|
401
401
|
|
|
402
402
|
- Highlight *code* as <template>`<code/>`</template>
|
|
@@ -226,7 +226,7 @@ related to a set of code quality aspects.
|
|
|
226
226
|
Generate a *new* proposal for the *same* <item/>
|
|
227
227
|
(incorporating the user's free-text hint from <result/> if
|
|
228
228
|
provided via the "OTHER" prefix) and loop back to substep 2
|
|
229
|
-
of this iteration. There is *no* cap on refinement rounds
|
|
229
|
+
of this iteration. There is *no* cap on refinement rounds -
|
|
230
230
|
keep refining until the user picks `ACCEPT` or `REJECT`.
|
|
231
231
|
</if>
|
|
232
232
|
|
|
@@ -20,7 +20,7 @@ into the user-visible transcript.
|
|
|
20
20
|
|
|
21
21
|
For each detected problem, the skill renders a unified-diff *SOLUTION*
|
|
22
22
|
preview and either asks the user to `ACCEPT` or `REJECT` the proposed
|
|
23
|
-
correction interactively or
|
|
23
|
+
correction interactively or - with `--auto` - applies all corrections
|
|
24
24
|
automatically.
|
|
25
25
|
|
|
26
26
|
## OPTIONS
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ase-docs-distill
|
|
3
|
+
argument-hint: "[--help|-h] [--top|-t <N>] <document-reference>"
|
|
4
|
+
description: >
|
|
5
|
+
Distill a provided document into a flat, importance-ranked list
|
|
6
|
+
of its key points, each with a salience rank, a rationale, and a
|
|
7
|
+
verbatim line-cited evidence snippet. Use when the user wants to
|
|
8
|
+
"distill", "summarize the key points", or "extract the essence" of a
|
|
9
|
+
document or pasted text.
|
|
10
|
+
user-invocable: true
|
|
11
|
+
disable-model-invocation: false
|
|
12
|
+
effort: high
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
|
|
16
|
+
@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
|
|
17
|
+
@${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
|
|
18
|
+
|
|
19
|
+
<skill name="ase-docs-distill">
|
|
20
|
+
Distill Key Points
|
|
21
|
+
</skill>
|
|
22
|
+
|
|
23
|
+
<expand name="getopt"
|
|
24
|
+
arg1="ase-docs-distill"
|
|
25
|
+
arg2="--top|-t=5">
|
|
26
|
+
$ARGUMENTS
|
|
27
|
+
</expand>
|
|
28
|
+
|
|
29
|
+
<objective>
|
|
30
|
+
*Distill* the content `<getopt-arguments/>` into a *flat*,
|
|
31
|
+
*importance-ranked* list of its *key points* - each point an
|
|
32
|
+
*atomic* claim carrying a *0-10 salience rank*, a *one-line
|
|
33
|
+
rationale*, and a *verbatim, line-cited evidence* snippet - keeping
|
|
34
|
+
at most `<getopt-option-top/>` points.
|
|
35
|
+
</objective>
|
|
36
|
+
|
|
37
|
+
Procedure
|
|
38
|
+
---------
|
|
39
|
+
|
|
40
|
+
You *MUST* follow the following numbered items *strictly* *sequentially*!
|
|
41
|
+
You *MUST* not skip any numbered item during processing!
|
|
42
|
+
|
|
43
|
+
You *MUST* *NOT* output anything in this entire procedure, *except* when
|
|
44
|
+
explicitly requested by this procedure via outputs based on a <template/>!
|
|
45
|
+
|
|
46
|
+
<flow>
|
|
47
|
+
|
|
48
|
+
1. <step id="STEP 1: Resolve Input">
|
|
49
|
+
|
|
50
|
+
Resolve the document source from <getopt-arguments/> using
|
|
51
|
+
*probe-as-file-first* semantics:
|
|
52
|
+
|
|
53
|
+
1. <if condition="<getopt-arguments/> is empty">
|
|
54
|
+
|
|
55
|
+
Only output the following <template/> and then *STOP* immediately:
|
|
56
|
+
|
|
57
|
+
<template>
|
|
58
|
+
⧉ **ASE**: ✪ skill: **ase-docs-distill**, ▶ status: **no document to distill**
|
|
59
|
+
</template>
|
|
60
|
+
|
|
61
|
+
</if>
|
|
62
|
+
|
|
63
|
+
2. Treat the *entire* <getopt-arguments/> as a *file path*. If it
|
|
64
|
+
resolves to a *readable file*, read that file and capture its
|
|
65
|
+
content together with its *line numbers* into <source/>, and set
|
|
66
|
+
<origin/> to the file path.
|
|
67
|
+
|
|
68
|
+
3. <if condition="<getopt-arguments/> does NOT resolve to a readable file">
|
|
69
|
+
|
|
70
|
+
Treat <getopt-arguments/> *verbatim* as *pasted text*, capture it
|
|
71
|
+
into <source/> numbering its lines from *1*, and set <origin/>
|
|
72
|
+
to empty (so locations are cited as `:Ls-Le`).
|
|
73
|
+
|
|
74
|
+
</if>
|
|
75
|
+
|
|
76
|
+
4. <if condition="<source/> is empty">
|
|
77
|
+
|
|
78
|
+
Only output the following <template/> and then *STOP* immediately:
|
|
79
|
+
|
|
80
|
+
<template>
|
|
81
|
+
⧉ **ASE**: ✪ skill: **ase-docs-distill**, ▶ status: **no document to distill**
|
|
82
|
+
</template>
|
|
83
|
+
|
|
84
|
+
</if>
|
|
85
|
+
|
|
86
|
+
You *MUST* *NOT* output anything in this STEP 1.
|
|
87
|
+
|
|
88
|
+
</step>
|
|
89
|
+
|
|
90
|
+
2. <step id="STEP 2: Distill Key Points">
|
|
91
|
+
|
|
92
|
+
Read <source/> and distill it into its *key points*.
|
|
93
|
+
|
|
94
|
+
1. Extract the document's *key points*, where each point is *one
|
|
95
|
+
atomic, self-contained claim, decision, or fact* - *not* a
|
|
96
|
+
section-level summary that blends several claims.
|
|
97
|
+
|
|
98
|
+
2. For each point, determine:
|
|
99
|
+
|
|
100
|
+
- A <rank/> on a *0-10* salience scale reflecting its
|
|
101
|
+
*importance-to-the-reader* (impact, centrality, consequence)
|
|
102
|
+
- *not* its position in the document.
|
|
103
|
+
|
|
104
|
+
- A one-line <rationale/> that justifies *why* the point earns
|
|
105
|
+
that <rank/>.
|
|
106
|
+
|
|
107
|
+
- A <location/> citing the exact source line range as
|
|
108
|
+
`<origin/>:Ls-Le` (for a file) or `:Ls-Le` (for pasted text),
|
|
109
|
+
where `Ls` is the start line and `Le` is the end line.
|
|
110
|
+
|
|
111
|
+
- A *verbatim* <evidence/> snippet, copied exactly from
|
|
112
|
+
<source/> (but with all newlines replaces with spaces
|
|
113
|
+
and multiple spaces collapsed into a single space), that
|
|
114
|
+
*proves* the point. The cited snippet *MUST* prove the
|
|
115
|
+
point verbatim. If it does not, *re-investigate and re-cite
|
|
116
|
+
correctly*.
|
|
117
|
+
|
|
118
|
+
3. *Sort* the points by <rank/> from *highest to lowest*. Within the
|
|
119
|
+
same rank, keep the order of first appearance in <source/>.
|
|
120
|
+
|
|
121
|
+
4. Apply the *top-bound* <getopt-option-top/> as an *upper bound
|
|
122
|
+
only*: keep at most `min(<getopt-option-top/>, number of salient
|
|
123
|
+
points)` points and *never pad* the list with filler to reach
|
|
124
|
+
the bound. If <getopt-option-top/> is *non-numeric* or *less
|
|
125
|
+
than or equal to 0*, use the default *10* instead.
|
|
126
|
+
|
|
127
|
+
You *MUST* *NOT* output anything in this STEP 2.
|
|
128
|
+
|
|
129
|
+
</step>
|
|
130
|
+
|
|
131
|
+
3. <step id="STEP 3: Report Ranked Points">
|
|
132
|
+
|
|
133
|
+
For each distilled point, emit the following <template/>,
|
|
134
|
+
where <rank/> is its salience rank, <point/> is the atomic claim,
|
|
135
|
+
<location/> is its line-range citation, <evidence/> is the
|
|
136
|
+
verbatim proving snippet, and <rationale/> is the one-line
|
|
137
|
+
salience justification:
|
|
138
|
+
|
|
139
|
+
<template>
|
|
140
|
+
|
|
141
|
+
<ase-tpl-bullet-normal/> **KEY POINT**: **<point/>**
|
|
142
|
+
|
|
143
|
+
◯ LOCATION: <location/>
|
|
144
|
+
◯ EVIDENCE: "`<evidence/>`"
|
|
145
|
+
◯ RATIONALE: <rationale/>
|
|
146
|
+
◯ RANK: <rank/>/10
|
|
147
|
+
|
|
148
|
+
</template>
|
|
149
|
+
|
|
150
|
+
In the <location/>, markup the line-range reference as
|
|
151
|
+
code (with backticks) and prepend it with `▢ `.
|
|
152
|
+
|
|
153
|
+
Keep the overall report *concise* and *brief*. Do *not* output any
|
|
154
|
+
further explanation.
|
|
155
|
+
|
|
156
|
+
</step>
|
|
157
|
+
|
|
158
|
+
</flow>
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
|
|
2
|
+
## NAME
|
|
3
|
+
|
|
4
|
+
`ase-docs-distill` - Distill Document Key Points
|
|
5
|
+
|
|
6
|
+
## SYNOPSIS
|
|
7
|
+
|
|
8
|
+
`ase-docs-distill`
|
|
9
|
+
[`--help`|`-h`]
|
|
10
|
+
[`--top`|`-t` *N*]
|
|
11
|
+
*document-reference*
|
|
12
|
+
|
|
13
|
+
## DESCRIPTION
|
|
14
|
+
|
|
15
|
+
The `ase-docs-distill` skill reads a *provided document* and distills it
|
|
16
|
+
into a *flat*, *importance-ranked* list of its *key points*. The
|
|
17
|
+
*docs-reference* is resolved *probe-as-file-first*: if the argument names
|
|
18
|
+
a *readable file* it is read from disk, otherwise the argument is taken
|
|
19
|
+
*verbatim* as *pasted text*. The document is read *silently* - only the
|
|
20
|
+
final ranked list is shown - so even a large document does not flood the
|
|
21
|
+
transcript.
|
|
22
|
+
|
|
23
|
+
Each emitted point is *one atomic claim, decision, or fact* (not a
|
|
24
|
+
section-level summary) and carries four things: a *0-10 salience rank*
|
|
25
|
+
reflecting its *importance to the reader* (impact and centrality, *not*
|
|
26
|
+
its position in the document), a *one-line rationale* justifying *why* it
|
|
27
|
+
earns that rank, an exact *line-range citation* (`file:Ls-Le`, or `:Ls-Le`
|
|
28
|
+
for pasted text), and a *verbatim evidence* snippet copied from the source
|
|
29
|
+
that *proves* the point. The points are emitted as a *bulleted list* -
|
|
30
|
+
one block per point, each showing its *LOCATION*, *EVIDENCE*,
|
|
31
|
+
*RATIONALE*, and *RANK* - sorted from highest to lowest salience, so the
|
|
32
|
+
ranking is *auditable* rather than an opaque ordering.
|
|
33
|
+
|
|
34
|
+
The `--top`/`-t` *N* option is a *length dial* that bounds the list to at
|
|
35
|
+
most *N* points (default *10*). It is an *upper bound only*: when the
|
|
36
|
+
document has fewer salient points than *N*, the skill emits only the
|
|
37
|
+
points it found and *never pads* the list with filler; a `0`, negative, or
|
|
38
|
+
non-numeric value falls back to the default *10*.
|
|
39
|
+
|
|
40
|
+
## ARGUMENTS
|
|
41
|
+
|
|
42
|
+
`--top`, `-t` *N*:
|
|
43
|
+
Bound the ranked list to at most *N* key points (default *10*). The
|
|
44
|
+
bound is a *cap*, never a *quota* - fewer points are emitted when the
|
|
45
|
+
document does not contain *N* salient ones, and an invalid or
|
|
46
|
+
non-positive *N* reverts to the default.
|
|
47
|
+
|
|
48
|
+
*docs-reference*:
|
|
49
|
+
The document to distill - either a *path* to a readable file or the
|
|
50
|
+
*text* itself pasted inline. If it resolves to a readable file the
|
|
51
|
+
file is read; otherwise it is treated verbatim as pasted text.
|
|
52
|
+
|
|
53
|
+
## EXAMPLES
|
|
54
|
+
|
|
55
|
+
Distill the key points of a document file:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
❯ /ase-docs-distill doc/architecture.md
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Distill only the top 5 key points:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
❯ /ase-docs-distill --top 5 doc/architecture.md
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Distill a pasted block of text:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
❯ /ase-docs-distill The system shall accept payments in EUR and USD only.
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## SEE ALSO
|
|
74
|
+
|
|
75
|
+
`ase-meta-search`, `ase-docs-proofread`, `ase-meta-why`.
|
|
76
|
+
|
|
@@ -175,7 +175,7 @@ Analyze documents for spelling, punctuation, or grammar errors
|
|
|
175
175
|
Generate a *new* proposal for the *same* <item/>,
|
|
176
176
|
incorporating the user's free-text hint from <result/>
|
|
177
177
|
after the "OTHER:" prefix, and loop back to substep 2 of
|
|
178
|
-
this iteration. There is *no* cap on refinement rounds
|
|
178
|
+
this iteration. There is *no* cap on refinement rounds -
|
|
179
179
|
keep refining until the user picks `ACCEPT` or `REJECT`.
|
|
180
180
|
|
|
181
181
|
</if>
|
|
@@ -20,7 +20,7 @@ the user-visible transcript.
|
|
|
20
20
|
|
|
21
21
|
For each detected problem, the skill renders a unified-diff
|
|
22
22
|
*CORRECTION* preview and either asks the user to `ACCEPT` or `REJECT`
|
|
23
|
-
the proposed correction interactively or
|
|
23
|
+
the proposed correction interactively or - with `--auto` - applies
|
|
24
24
|
all corrections automatically.
|
|
25
25
|
|
|
26
26
|
## OPTIONS
|
|
@@ -33,8 +33,8 @@ Guiding Tenets
|
|
|
33
33
|
Honor the following tenets throughout the brainstorming:
|
|
34
34
|
|
|
35
35
|
- **No Assumption of Simplicity**:
|
|
36
|
-
Every topic goes through the full process
|
|
37
|
-
change as much as a new subsystem
|
|
36
|
+
Every topic goes through the full process - a one-line config
|
|
37
|
+
change as much as a new subsystem - because the simplest-looking
|
|
38
38
|
topics often hide the most harmful assumptions.
|
|
39
39
|
|
|
40
40
|
- **Explore Intent First**:
|
|
@@ -83,9 +83,15 @@ Honor the following tenets throughout the brainstorming:
|
|
|
83
83
|
|
|
84
84
|
Before generating any ideas, *explore the project context* (review
|
|
85
85
|
relevant existing files, documentation, and recent changes) and
|
|
86
|
-
determine the <m/> *essential unknowns* about the topic
|
|
87
|
-
purpose, constraints, scope boundaries, and success criteria
|
|
88
|
-
must be pinned down for the brainstorming to be reasonably
|
|
86
|
+
determine the <m/> (<m/>=1-3) *essential unknowns* about the topic
|
|
87
|
+
- the purpose, constraints, scope boundaries, and success criteria
|
|
88
|
+
that must be pinned down for the brainstorming to be reasonably
|
|
89
|
+
grounded.
|
|
90
|
+
|
|
91
|
+
Notice: you are intentionally constraint to just 1-3 unknowns,
|
|
92
|
+
as too much upfront intent clarification kills the brainstorming
|
|
93
|
+
of ideas later. So, you *MUST* reduce the clarifications of the
|
|
94
|
+
unknowns to the absolute minimum!
|
|
89
95
|
|
|
90
96
|
For each essential unknown, derive a short 1-3 word facet <facet-M/>
|
|
91
97
|
and a corresponding question <question-M/> whose answer materially
|
|
@@ -139,10 +145,10 @@ Honor the following tenets throughout the brainstorming:
|
|
|
139
145
|
<topic/> within the constraints established by the answers
|
|
140
146
|
<answer-M/>.
|
|
141
147
|
|
|
142
|
-
Deliberately pursue *diverse angles*
|
|
148
|
+
Deliberately pursue *diverse angles* - e.g. the minimal/MVP-first
|
|
143
149
|
angle, the robustness/risk-first angle, the user-experience-first
|
|
144
150
|
angle, the reuse-existing-machinery angle, the coolness angle, and
|
|
145
|
-
the unconventional/wildcard angle
|
|
151
|
+
the unconventional/wildcard angle - because variety in origin yields
|
|
146
152
|
variety in outcome.
|
|
147
153
|
|
|
148
154
|
Do still *not* judge, rank, or prune ideas in this step. Generate
|
|
@@ -177,7 +183,7 @@ Honor the following tenets throughout the brainstorming:
|
|
|
177
183
|
statement of not more than 40 words):
|
|
178
184
|
|
|
179
185
|
<template>
|
|
180
|
-
<ase-tpl-bullet-secondary/> **IDEA CLUSTER <C/>/<c/>**: <cluster-C/>
|
|
186
|
+
<ase-tpl-bullet-secondary/> **IDEA CLUSTER <C/>/<c/>**: <cluster-C/> - <cluster-summary-C/>,
|
|
181
187
|
**IDEAS**: <N/>, <M/>[, ...]
|
|
182
188
|
</template>
|
|
183
189
|
|
|
@@ -191,7 +197,7 @@ Honor the following tenets throughout the brainstorming:
|
|
|
191
197
|
3-4 options, sorted by rank from highest to lowest.
|
|
192
198
|
|
|
193
199
|
For this, draw the shortlist from *distinct* clusters <cluster-C/>
|
|
194
|
-
wherever possible
|
|
200
|
+
wherever possible - prefer a diverse shortlist spanning different
|
|
195
201
|
clusters over several high-ranked variations of the same cluster,
|
|
196
202
|
unless one cluster clearly dominates on rank.
|
|
197
203
|
|
|
@@ -205,9 +211,9 @@ Honor the following tenets throughout the brainstorming:
|
|
|
205
211
|
<ase-tpl-bullet-normal/> **DISTILLED IDEA <N/>**: <option-N/>
|
|
206
212
|
</template>
|
|
207
213
|
|
|
208
|
-
4. Finally, derive a single *recommended idea*
|
|
214
|
+
4. Finally, derive a single *recommended idea* - the highest-ranked
|
|
209
215
|
option, or a principled synthesis of the option shortlist that preserves
|
|
210
|
-
what is strongest in each
|
|
216
|
+
what is strongest in each - store its one-sentence rationale (not
|
|
211
217
|
more than 40 words) in <recommendation/>, and output the following
|
|
212
218
|
<template/>:
|
|
213
219
|
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
The `ase-meta-brainstorm` skill guides a collaborative ideation
|
|
15
15
|
session on a *topic* *before* any implementation begins. It first
|
|
16
16
|
*clarifies intent* by exploring the project context and interviewing
|
|
17
|
-
the user
|
|
17
|
+
the user - one grounded, multiple-choice question at a time - about
|
|
18
18
|
purpose, constraints, scope, and success criteria. It then *diverges*
|
|
19
19
|
into a broad space of candidate ideas pursued from deliberately diverse
|
|
20
20
|
angles (MVP-first, risk-first, UX-first, reuse-first, and wildcard),
|
|
@@ -23,8 +23,8 @@ without judging them.
|
|
|
23
23
|
Next it *converges* by clustering the ideas into coherent themes,
|
|
24
24
|
pruning speculative or out-of-scope ones via *YAGNI*, and scoring the
|
|
25
25
|
survivors on a 0-10 fit scale (keeping only those ranked 7 or higher).
|
|
26
|
-
Finally it distills a *shortlist* of the top 3-4 directions
|
|
27
|
-
distinct clusters wherever possible
|
|
26
|
+
Finally it distills a *shortlist* of the top 3-4 directions - drawn from
|
|
27
|
+
distinct clusters wherever possible - and derives a single
|
|
28
28
|
*RECOMMENDATION*, being either the highest-ranked option or a principled
|
|
29
29
|
synthesis of the shortlist.
|
|
30
30
|
|
|
@@ -35,7 +35,7 @@ recommended direction off to the `ase-task-edit`, `ase-code-craft`, or
|
|
|
35
35
|
## ARGUMENTS
|
|
36
36
|
|
|
37
37
|
*topic*:
|
|
38
|
-
The subject to brainstorm
|
|
38
|
+
The subject to brainstorm - a feature, component, behavior, or
|
|
39
39
|
design question to explore *what* to build before *how*.
|
|
40
40
|
|
|
41
41
|
## EXAMPLES
|
|
@@ -30,9 +30,9 @@ effort: xhigh
|
|
|
30
30
|
<ase-tpl-bullet-secondary/> **THESIS**: <thesis/>
|
|
31
31
|
</template>
|
|
32
32
|
|
|
33
|
-
2. **Determine Anti-
|
|
33
|
+
2. **Determine Anti-Theses**:
|
|
34
34
|
|
|
35
|
-
Reason on the thesis in <thesis/> by playing *Devil
|
|
35
|
+
Reason on the thesis in <thesis/> by playing *Devil's Advocate*
|
|
36
36
|
(latin: *Advocatus Diaboli*) by relentlessly challenging or
|
|
37
37
|
criticising it with the help of the following tenets:
|
|
38
38
|
|
|
@@ -47,7 +47,7 @@ effort: xhigh
|
|
|
47
47
|
of polish on the surface can save what is built on top of it.
|
|
48
48
|
|
|
49
49
|
- **Target Claims, Not Person**:
|
|
50
|
-
Critique the thesis, the assumption, the evidence
|
|
50
|
+
Critique the thesis, the assumption, the evidence - never the
|
|
51
51
|
proponent's competence or motives, because the moment it gets
|
|
52
52
|
personal, the inquiry dies.
|
|
53
53
|
|
|
@@ -133,7 +133,7 @@ effort: xhigh
|
|
|
133
133
|
while ignoring its own limits, gaps, or internal tensions.
|
|
134
134
|
|
|
135
135
|
- *Antithesis*: the opposing force. It is the contradiction,
|
|
136
|
-
objection, or counter-position that the thesis provokes
|
|
136
|
+
objection, or counter-position that the thesis provokes - precisely
|
|
137
137
|
the role a Devil's Advocate played. The antithesis exposes what the
|
|
138
138
|
thesis omitted or got wrong.
|
|
139
139
|
|
|
@@ -14,10 +14,10 @@
|
|
|
14
14
|
The `ase-meta-diaboli` skill plays *Devil's Advocate* (latin:
|
|
15
15
|
*Advocatus Diaboli*) by relentlessly challenging or criticising a
|
|
16
16
|
supplied *thesis*. It applies a disciplined set of critical-thinking
|
|
17
|
-
tenets
|
|
17
|
+
tenets - steelmanning, stress-testing fundamentals, surfacing implicit
|
|
18
18
|
assumptions, demanding proportional evidence, seeking disconfirming
|
|
19
19
|
cases, *Reductio Ad Absurdum*, exposing hidden costs, and pre-mortem
|
|
20
|
-
thinking
|
|
20
|
+
thinking - while targeting the claim rather than its proponent and
|
|
21
21
|
yielding where the argument genuinely holds.
|
|
22
22
|
|
|
23
23
|
The skill iterates until it has found at least ten anti-theses
|