codex

Name: codex
Author: arkbriar

31stars1forks

How to install codex?

arkbriar/sisyphus-design/codex

$npx -y skills add arkbriar/sisyphus-design --skill codex

Installs into the current project.

Summary

Produce high-quality design documents through research, divergent thinking, and iterative refinement. Use when asked to design a system, component, or architecture — e.g., "design a task queue", "write a design doc for X", or any request that needs a structured design document wi

Files · 1

View on GitHub

SKILL.md

1	# Design Skill
2
3	Design requirement: {user's request}
4
5	If no requirement is provided, use request_user_input to ask for the design requirement before proceeding.
6
7	Read before starting:
8	- [references/template.md](references/template.md) — document structure for drafting
9	- [references/checklist.md](references/checklist.md) — evaluation criteria for review
10
11	## Phase 0: Research & Diverge (no human)
12
13	For trivial requirements (single flag, simple rename, obvious-one-solution), skip Phase 0 and Phase 1 — go directly to Phase 2. Present a single approach and identify the consumer as part of the decision presentation.
14
15	1. Investigate: spawn a fresh research subagent. It receives the design requirement and returns a structured summary: existing patterns found, constraints discovered, relevant prior art. Use web search whenever the domain is unfamiliar, prior art may exist, or something is unclear. Keep the main context clean — only bring back the summary.
16	2. Think from first principles: what is this system fundamentally trying to do? What are the core constraints? Strip away conventional framing and reason from the ground up.
17	3. Identify the critical path: the component or decision that, if wrong, makes the system fail regardless of how good everything else is.
18	4. Generate 2-3 fundamentally different approaches that diverge on the critical path. Reuse obvious choices elsewhere.
19	5. For each approach: one-sentence core idea, key trade-off, when it fails.
20
21	## Phase 1: Interrogate (human)
22
23	Use request_user_input to present concisely:
24	1. Consumer: who implements from this design. Their first unanswered question.
25	2. Critical path: the component or decision from Phase 0. Why this is the critical path.
26	3. Approaches: the 2-3 from Phase 0 with trade-offs.
27	4. Recommended approach: which one and why, based on the analysis.
28	5. Discriminating questions: only questions whose answer would change the recommendation.
29
30	Wait for answers. User confirms, redirects, or asks follow-ups.
31
32	## Phase 2: Decisions (human)
33
34	1. Present the decisions as conversation text per the Decision Log format in [references/template.md](references/template.md), including expanded blocks for critical path decisions and the end-to-end example trace (what data enters, what choices apply, what comes out — component-level state detail comes in Phase 3).
35	2. Use request_user_input to collect feedback — approve, reject, or comment. Keep the question short; do not repeat the decisions.
36	3. Revise if rejected. All open questions must be answered before proceeding. If the user or the decisions reveal the requirement is more complex than initially assessed (especially if the trivial shortcut was used), return to Phase 0 for proper research.
37
38	## Phase 3: Draft & Refine (no human)
39
40	1. Draft the design using [references/template.md](references/template.md). Write to `design/<name>.md`. Derive `<name>` as `YYYY-MM-DD-<topic>` (e.g., `2026-03-19-auth`). If that file already exists, append `-2`, `-3`, etc. Where the input is ambiguous, state the ambiguity and chosen interpretation in the design. Carry the Phase 2 example trace into the Interactions section, updating it to match final component names.
41	2. Self-check against [references/checklist.md](references/checklist.md), skipping procedure step 0b (baseline sketch — the author cannot objectively evaluate their own design against a baseline). Fix all issues found.
42	3. Spawn a fresh evaluator subagent. The subagent must:
43	- Have NO context about the design's history, decisions, or prior findings
44	- Read the design file and [references/checklist.md](references/checklist.md)
45	- Read the original design requirement and the Phase 0 research summary (pass both in the subagent prompt). The approved decision log is already in the design file's Decision Log section.
46	- Output findings per checklist format
47	4. Fix root cause clusters first. Then do a nit pass on remaining SPECIFY/ACKNOWLEDGE findings — a pile of small issues is still a quality problem.
48	5. Convergence check — open a finding ledger for this refinement loop:
49	- Each finding = question number + concepts touched + concrete gap description
50	- Two findings match if same question and same concepts
51	- Track resolved vs new findings each cycle
52	- Stop if: 0 REDESIGN FAILs, or 3 evaluator cycles reached
53	- Otherwise: loop back to step 3
54	- At stop: outstanding REDESIGN FAILs become Known Limitations in the design.
55	6. Present the design file to the user.
56
57	## Phase 4: Review (human)
58
59	User reads the design file and provides comments.
60
61	## Phase 5: Refine from Comments (no human)
62
63	O

People who liked this also viewed

6 picks

Type

codex

31stars1forks

View on GitHub

How to install codex?

arkbriar/sisyphus-design/codex

$npx -y skills add arkbriar/sisyphus-design --skill codex

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Design Skill
2
3	Design requirement: {user's request}
4
5	If no requirement is provided, use request_user_input to ask for the design requirement before proceeding.
6
7	Read before starting:
8	- [references/template.md](references/template.md) — document structure for drafting
9	- [references/checklist.md](references/checklist.md) — evaluation criteria for review
10
11	## Phase 0: Research & Diverge (no human)
12
13	For trivial requirements (single flag, simple rename, obvious-one-solution), skip Phase 0 and Phase 1 — go directly to Phase 2. Present a single approach and identify the consumer as part of the decision presentation.
14
15	1. Investigate: spawn a fresh research subagent. It receives the design requirement and returns a structured summary: existing patterns found, constraints discovered, relevant prior art. Use web search whenever the domain is unfamiliar, prior art may exist, or something is unclear. Keep the main context clean — only bring back the summary.
16	2. Think from first principles: what is this system fundamentally trying to do? What are the core constraints? Strip away conventional framing and reason from the ground up.
17	3. Identify the critical path: the component or decision that, if wrong, makes the system fail regardless of how good everything else is.
18	4. Generate 2-3 fundamentally different approaches that diverge on the critical path. Reuse obvious choices elsewhere.
19	5. For each approach: one-sentence core idea, key trade-off, when it fails.
20
21	## Phase 1: Interrogate (human)
22
23	Use request_user_input to present concisely:
24	1. Consumer: who implements from this design. Their first unanswered question.
25	2. Critical path: the component or decision from Phase 0. Why this is the critical path.
26	3. Approaches: the 2-3 from Phase 0 with trade-offs.
27	4. Recommended approach: which one and why, based on the analysis.
28	5. Discriminating questions: only questions whose answer would change the recommendation.
29
30	Wait for answers. User confirms, redirects, or asks follow-ups.
31
32	## Phase 2: Decisions (human)
33
34	1. Present the decisions as conversation text per the Decision Log format in [references/template.md](references/template.md), including expanded blocks for critical path decisions and the end-to-end example trace (what data enters, what choices apply, what comes out — component-level state detail comes in Phase 3).
35	2. Use request_user_input to collect feedback — approve, reject, or comment. Keep the question short; do not repeat the decisions.
36	3. Revise if rejected. All open questions must be answered before proceeding. If the user or the decisions reveal the requirement is more complex than initially assessed (especially if the trivial shortcut was used), return to Phase 0 for proper research.
37
38	## Phase 3: Draft & Refine (no human)
39
40	1. Draft the design using [references/template.md](references/template.md). Write to `design/<name>.md`. Derive `<name>` as `YYYY-MM-DD-<topic>` (e.g., `2026-03-19-auth`). If that file already exists, append `-2`, `-3`, etc. Where the input is ambiguous, state the ambiguity and chosen interpretation in the design. Carry the Phase 2 example trace into the Interactions section, updating it to match final component names.
41	2. Self-check against [references/checklist.md](references/checklist.md), skipping procedure step 0b (baseline sketch — the author cannot objectively evaluate their own design against a baseline). Fix all issues found.
42	3. Spawn a fresh evaluator subagent. The subagent must:
43	- Have NO context about the design's history, decisions, or prior findings
44	- Read the design file and [references/checklist.md](references/checklist.md)
45	- Read the original design requirement and the Phase 0 research summary (pass both in the subagent prompt). The approved decision log is already in the design file's Decision Log section.
46	- Output findings per checklist format
47	4. Fix root cause clusters first. Then do a nit pass on remaining SPECIFY/ACKNOWLEDGE findings — a pile of small issues is still a quality problem.
48	5. Convergence check — open a finding ledger for this refinement loop:
49	- Each finding = question number + concepts touched + concrete gap description
50	- Two findings match if same question and same concepts
51	- Track resolved vs new findings each cycle
52	- Stop if: 0 REDESIGN FAILs, or 3 evaluator cycles reached
53	- Otherwise: loop back to step 3
54	- At stop: outstanding REDESIGN FAILs become Known Limitations in the design.
55	6. Present the design file to the user.
56
57	## Phase 4: Review (human)
58
59	User reads the design file and provides comments.
60
61	## Phase 5: Refine from Comments (no human)
62
63	O

People who liked this also viewed

6 picks

Type