diff --git a/harness/pstack/claude-code/skills/arena/SKILL.md b/harness/pstack/claude-code/skills/arena/SKILL.md index 1aa77e452..69a30f455 100644 --- a/harness/pstack/claude-code/skills/arena/SKILL.md +++ b/harness/pstack/claude-code/skills/arena/SKILL.md @@ -41,10 +41,12 @@ Walk each losing candidate once more for what is worth porting into the base, us If the candidates converge on one shape, that is strong agreement. Note it and ship the consensus shape. No graft is needed. If they wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. +Write one synthesis note that names what it overrides in the base. That note is the only implementation contract. The implementer prompt cites that path and the exact verify commands, not the base sketch the note overrides. + ## Phase F: Verify -Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it. +Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. The parent checks the merged tree against the synthesis contract. The implementer's own pass count is not that check. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it. ## Outputs -One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result. +One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result. When the run is multi-hour or unattended, copy the synthesis and the grounding into the show-me-your-work trail. A scratch directory under `/tmp` is not that trail. diff --git a/harness/pstack/claude-code/skills/how/SKILL.md b/harness/pstack/claude-code/skills/how/SKILL.md index b378f87fe..114215b4a 100644 --- a/harness/pstack/claude-code/skills/how/SKILL.md +++ b/harness/pstack/claude-code/skills/how/SKILL.md @@ -27,7 +27,7 @@ Decompose the question into 2 to 4 angles, each a distinct slice of the subsyste ## 3. Synthesize (complex only) -Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. +Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. An explorer has returned only when its transcript output exists. A Task status field is not completion. ## 4. Present diff --git a/harness/pstack/claude-code/skills/poteto-mode/SKILL.md b/harness/pstack/claude-code/skills/poteto-mode/SKILL.md index 1bb3884a5..baf55f963 100644 --- a/harness/pstack/claude-code/skills/poteto-mode/SKILL.md +++ b/harness/pstack/claude-code/skills/poteto-mode/SKILL.md @@ -35,7 +35,7 @@ Remaining triggers: - Asked to land or ship a green stack → the **Shipping** playbook (`playbooks/shipping.md`). Green is not safe. Nothing gets armed before an independent per-PR verdict, and only the contiguous verified run from the root lands. - Bugbot or the agentic security review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask per `references/bugbot-triage.md`. - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it. -- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Commit it when stakes need an auditable record. Keep it local otherwise. +- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Copy arena synthesis and grounding into that trail when the run is multi-hour or unattended. A scratch directory under `/tmp` is not the trail. Commit it when stakes need an auditable record. Keep it local otherwise. ## Principles diff --git a/harness/pstack/claude-code/skills/poteto-mode/playbooks/feature.md b/harness/pstack/claude-code/skills/poteto-mode/playbooks/feature.md index eb1040cb2..4f3096ff1 100644 --- a/harness/pstack/claude-code/skills/poteto-mode/playbooks/feature.md +++ b/harness/pstack/claude-code/skills/poteto-mode/playbooks/feature.md @@ -2,18 +2,18 @@ **You own the design. Plan, review, verify.** Delegate implementation. Stay in the lead. -1. `how` over the affected subsystem. +1. `how` over the affected subsystem. When this mode already owns a named milestone, scope from that milestone's design doc, scratch issue, and the repository's agent change fences, and do not also start the sequential plan skill. Infer what already shipped from `git log` on the touched crates and from `gh pr view` (or the resolved forge) before asking the user. 2. `architect` for parallel design exploration. 3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: ` rather than being dropped: - - **Blocking first steps.** Gates run before fan-out. + - **Blocking first steps.** Gates run before fan-out. Put an observable outcome matrix in the design artifact, with at least one acceptance test per row that asserts the committed user-visible result. Name the tests that encoded the old contract and must change when that result shifts. - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. +4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. When an arena synthesis file overrides the base sketch, the delegate prompt cites only that file and the exact verify commands. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. Name the acceptance surface from the contract, and fail the step when the verify commands exercise only a narrower proxy. After a delegate reports success, read the diff against the written contract, then re-run the named verify commands. A green count is not the contract. 6. Rebase into small, ordered commits. Stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. -7. If the design is contested, `interrogate` before shipping. +7. If the design is contested, `interrogate` before shipping. Also interrogate when the rubric that picked the design exercises a narrower surface than the contract's end-to-end acceptance story. 8. Run **Opening a PR**. Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline. That owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries. Spawn a fresh owner rather than chaining interrupts. diff --git a/harness/pstack/claude-code/skills/poteto-mode/playbooks/opening-a-pr.md b/harness/pstack/claude-code/skills/poteto-mode/playbooks/opening-a-pr.md index d729a7a06..e58c2b514 100644 --- a/harness/pstack/claude-code/skills/poteto-mode/playbooks/opening-a-pr.md +++ b/harness/pstack/claude-code/skills/poteto-mode/playbooks/opening-a-pr.md @@ -4,9 +4,9 @@ Invoked at the end of every other playbook. **Worktree.** Work from a git worktree off main. Subagents inherit it. Multiple `Task` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally. -**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject. +**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story, and green on its own, with every new symbol already used by something in that same tree. A dependency-only commit that fails checks is not a unit. Squash or reorder it instead of narrating the broken tree. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject. -**PRs.** Run `/deslop` from `cursor-team-kit` over the diff before commit and `/no-comments` before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`. +**PRs.** Before creating a pull request, view the branch on the resolved forge. When one is already open, edit that pull request instead of opening a second. Run `/deslop` from `cursor-team-kit` over the diff before commit and `/no-comments` before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`. **Titles.** Conventional Commits `type(scope): subject`, no trailing period. Type such as `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf`. Scope is the area, such as `pstack` or `poteto-mode`. Subject is short, imperative, and names a real symbol when one carries the change, for example `fix(pstack): retarget opening-a-pr babysit trigger`. @@ -27,7 +27,7 @@ After the sections, attach videos or screenshots when they prove a claim. Full S **Size and stacks.** Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. As a parent merges, move its child onto trunk per `playbooks/shipping.md` step 4. Without a built-in PR tool, per the resolved forge, create a child with `origin pr create --status open --base ` or `gh pr create --base `, and retarget one with `origin pr edit --base ` or `gh pr edit --base `. Branch from trunk only for independent work. Rebase on trunk before substantial stack work. -**Readiness.** Open every PR ready, never as a draft. A built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft, mark it ready through the PR tool, or run `origin pr ready ` or `gh pr ready ` according to the resolved forge. Run `origin pr view ` or `gh pr view ` before you refer to PR status. +**Readiness.** Open every PR ready, never as a draft, unless the user or the playbook explicitly says to create or keep a draft. That instruction overrides this default: pass `--draft` on create, or run `gh pr ready --undo` (or the Origin equivalent). Otherwise a built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft and that override does not apply, mark it ready through the PR tool, or run `origin pr ready ` or `gh pr ready ` according to the resolved forge. Run `origin pr view ` or `gh pr view ` before you refer to PR status. **Babysit.** Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks for one after the whole stack exists. A babysit for each new PR stalls the build and spends checks on commits later waves restart. Push back when feedback drifts from intent. diff --git a/harness/pstack/claude-code/skills/principle-boundary-discipline/SKILL.md b/harness/pstack/claude-code/skills/principle-boundary-discipline/SKILL.md index dfe9a6fb0..7f4126f40 100644 --- a/harness/pstack/claude-code/skills/principle-boundary-discipline/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-boundary-discipline/SKILL.md @@ -17,6 +17,9 @@ Place validation, type narrowing, and error handling at system boundaries. Trust **Applications:** +Parsing boundaries: +- Keep typed user entry and document-relative resolution on separate paths. Do not send a fragment-only or path-relative reference through the typed-entry normalizer. + Validation and error handling: - Validate config at parse time (the boundary), not inside business logic - Parse raw data into domain types at the boundary diff --git a/harness/pstack/claude-code/skills/principle-prove-it-works/SKILL.md b/harness/pstack/claude-code/skills/principle-prove-it-works/SKILL.md index 31df67d63..9261ee224 100644 --- a/harness/pstack/claude-code/skills/principle-prove-it-works/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-prove-it-works/SKILL.md @@ -15,6 +15,7 @@ Verify every task output by checking the real thing directly. Do not infer from Check the real thing, not a proxy: - Check process liveness directly, not indirectly through derived state - Read the actual value, not a cached or derived representation +- After a delegate reports success, read the diff against the written contract, then re-run the named checks. A passing count is not the contract. - When verification fails, suspect the observation method before suspecting the system ## Script the check when you can diff --git a/harness/pstack/claude-code/skills/principle-sequence-verifiable-units/SKILL.md b/harness/pstack/claude-code/skills/principle-sequence-verifiable-units/SKILL.md index 986371260..ecb2845f7 100644 --- a/harness/pstack/claude-code/skills/principle-sequence-verifiable-units/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-sequence-verifiable-units/SKILL.md @@ -12,6 +12,6 @@ Order work as a sequence of small units, each ending in a state you can check, a **Execution.** In a sweep, migration, or any run of similar edits, verify each change before starting the next. Each unit is a before/after bracket: known-good state, one change, run the check, then proceed. Rebase onto clean trunk first so every check measures against the real baseline. When a lever does the edits, the per-unit check is nearly free. Run it anyway. -**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument. +**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument. A commit is a unit only when that tree is green and every new symbol already has the consumer it needs. A dependency-only commit that fails checks is not a unit. Squash or reorder it. The sequencing complement to the **prove-it-works** principle skill, which keeps each check real, and the **build-the-lever** principle skill, which makes the per-unit check cheap. diff --git a/pstack/skills/arena/SKILL.md b/pstack/skills/arena/SKILL.md index b198b9e42..96ca961ec 100644 --- a/pstack/skills/arena/SKILL.md +++ b/pstack/skills/arena/SKILL.md @@ -39,10 +39,12 @@ Walk each losing candidate once more for what is worth porting into the base, us If the candidates converge on one shape, that is strong agreement. Note it and ship the consensus shape. No graft is needed. If they wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. +Write one synthesis note that names what it overrides in the base. That note is the only implementation contract. The implementer prompt cites that path and the exact verify commands, not the base sketch the note overrides. + ## Phase F: Verify -Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it. +Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. The parent checks the merged tree against the synthesis contract. The implementer's own pass count is not that check. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it. ## Outputs -One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result. +One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result. When the run is multi-hour or unattended, copy the synthesis and the grounding into the show-me-your-work trail. A scratch directory under `/tmp` is not that trail. diff --git a/pstack/skills/how/SKILL.md b/pstack/skills/how/SKILL.md index 67edc340d..6d87e72a8 100644 --- a/pstack/skills/how/SKILL.md +++ b/pstack/skills/how/SKILL.md @@ -25,7 +25,7 @@ Decompose the question into 2 to 4 angles, each a distinct slice of the subsyste ## 3. Synthesize (complex only) -Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. +Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. An explorer has returned only when its transcript output exists. A Task status field is not completion. ## 4. Present diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index 21993f546..f071b0fa4 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/pstack/skills/poteto-mode/SKILL.md @@ -33,7 +33,7 @@ Remaining triggers: - Asked to land or ship a green stack → the **Shipping** playbook (`playbooks/shipping.md`). Green is not safe. Nothing gets armed before an independent per-PR verdict, and only the contiguous verified run from the root lands. - Bugbot or the agentic security review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask per `references/bugbot-triage.md`. - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it. -- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Commit it when stakes need an auditable record. Keep it local otherwise. +- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Copy arena synthesis and grounding into that trail when the run is multi-hour or unattended. A scratch directory under `/tmp` is not the trail. Commit it when stakes need an auditable record. Keep it local otherwise. ## Principles diff --git a/pstack/skills/poteto-mode/playbooks/feature.md b/pstack/skills/poteto-mode/playbooks/feature.md index eb1040cb2..4f3096ff1 100644 --- a/pstack/skills/poteto-mode/playbooks/feature.md +++ b/pstack/skills/poteto-mode/playbooks/feature.md @@ -2,18 +2,18 @@ **You own the design. Plan, review, verify.** Delegate implementation. Stay in the lead. -1. `how` over the affected subsystem. +1. `how` over the affected subsystem. When this mode already owns a named milestone, scope from that milestone's design doc, scratch issue, and the repository's agent change fences, and do not also start the sequential plan skill. Infer what already shipped from `git log` on the touched crates and from `gh pr view` (or the resolved forge) before asking the user. 2. `architect` for parallel design exploration. 3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: ` rather than being dropped: - - **Blocking first steps.** Gates run before fan-out. + - **Blocking first steps.** Gates run before fan-out. Put an observable outcome matrix in the design artifact, with at least one acceptance test per row that asserts the committed user-visible result. Name the tests that encoded the old contract and must change when that result shifts. - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. +4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. When an arena synthesis file overrides the base sketch, the delegate prompt cites only that file and the exact verify commands. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. Name the acceptance surface from the contract, and fail the step when the verify commands exercise only a narrower proxy. After a delegate reports success, read the diff against the written contract, then re-run the named verify commands. A green count is not the contract. 6. Rebase into small, ordered commits. Stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. -7. If the design is contested, `interrogate` before shipping. +7. If the design is contested, `interrogate` before shipping. Also interrogate when the rubric that picked the design exercises a narrower surface than the contract's end-to-end acceptance story. 8. Run **Opening a PR**. Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline. That owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries. Spawn a fresh owner rather than chaining interrupts. diff --git a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md index d729a7a06..e58c2b514 100644 --- a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md +++ b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md @@ -4,9 +4,9 @@ Invoked at the end of every other playbook. **Worktree.** Work from a git worktree off main. Subagents inherit it. Multiple `Task` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally. -**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject. +**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story, and green on its own, with every new symbol already used by something in that same tree. A dependency-only commit that fails checks is not a unit. Squash or reorder it instead of narrating the broken tree. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject. -**PRs.** Run `/deslop` from `cursor-team-kit` over the diff before commit and `/no-comments` before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`. +**PRs.** Before creating a pull request, view the branch on the resolved forge. When one is already open, edit that pull request instead of opening a second. Run `/deslop` from `cursor-team-kit` over the diff before commit and `/no-comments` before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`. **Titles.** Conventional Commits `type(scope): subject`, no trailing period. Type such as `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf`. Scope is the area, such as `pstack` or `poteto-mode`. Subject is short, imperative, and names a real symbol when one carries the change, for example `fix(pstack): retarget opening-a-pr babysit trigger`. @@ -27,7 +27,7 @@ After the sections, attach videos or screenshots when they prove a claim. Full S **Size and stacks.** Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. As a parent merges, move its child onto trunk per `playbooks/shipping.md` step 4. Without a built-in PR tool, per the resolved forge, create a child with `origin pr create --status open --base ` or `gh pr create --base `, and retarget one with `origin pr edit --base ` or `gh pr edit --base `. Branch from trunk only for independent work. Rebase on trunk before substantial stack work. -**Readiness.** Open every PR ready, never as a draft. A built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft, mark it ready through the PR tool, or run `origin pr ready ` or `gh pr ready ` according to the resolved forge. Run `origin pr view ` or `gh pr view ` before you refer to PR status. +**Readiness.** Open every PR ready, never as a draft, unless the user or the playbook explicitly says to create or keep a draft. That instruction overrides this default: pass `--draft` on create, or run `gh pr ready --undo` (or the Origin equivalent). Otherwise a built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft and that override does not apply, mark it ready through the PR tool, or run `origin pr ready ` or `gh pr ready ` according to the resolved forge. Run `origin pr view ` or `gh pr view ` before you refer to PR status. **Babysit.** Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks for one after the whole stack exists. A babysit for each new PR stalls the build and spends checks on commits later waves restart. Push back when feedback drifts from intent. diff --git a/pstack/skills/principle-boundary-discipline/SKILL.md b/pstack/skills/principle-boundary-discipline/SKILL.md index dfe9a6fb0..7f4126f40 100644 --- a/pstack/skills/principle-boundary-discipline/SKILL.md +++ b/pstack/skills/principle-boundary-discipline/SKILL.md @@ -17,6 +17,9 @@ Place validation, type narrowing, and error handling at system boundaries. Trust **Applications:** +Parsing boundaries: +- Keep typed user entry and document-relative resolution on separate paths. Do not send a fragment-only or path-relative reference through the typed-entry normalizer. + Validation and error handling: - Validate config at parse time (the boundary), not inside business logic - Parse raw data into domain types at the boundary diff --git a/pstack/skills/principle-prove-it-works/SKILL.md b/pstack/skills/principle-prove-it-works/SKILL.md index 5dc14a3b0..150fef122 100644 --- a/pstack/skills/principle-prove-it-works/SKILL.md +++ b/pstack/skills/principle-prove-it-works/SKILL.md @@ -13,6 +13,7 @@ Verify every task output by checking the real thing directly. Do not infer from Check the real thing, not a proxy: - Check process liveness directly, not indirectly through derived state - Read the actual value, not a cached or derived representation +- After a delegate reports success, read the diff against the written contract, then re-run the named checks. A passing count is not the contract. - When verification fails, suspect the observation method before suspecting the system ## Script the check when you can diff --git a/pstack/skills/principle-sequence-verifiable-units/SKILL.md b/pstack/skills/principle-sequence-verifiable-units/SKILL.md index 986371260..ecb2845f7 100644 --- a/pstack/skills/principle-sequence-verifiable-units/SKILL.md +++ b/pstack/skills/principle-sequence-verifiable-units/SKILL.md @@ -12,6 +12,6 @@ Order work as a sequence of small units, each ending in a state you can check, a **Execution.** In a sweep, migration, or any run of similar edits, verify each change before starting the next. Each unit is a before/after bracket: known-good state, one change, run the check, then proceed. Rebase onto clean trunk first so every check measures against the real baseline. When a lever does the edits, the per-unit check is nearly free. Run it anyway. -**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument. +**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument. A commit is a unit only when that tree is green and every new symbol already has the consumer it needs. A dependency-only commit that fails checks is not a unit. Squash or reorder it. The sequencing complement to the **prove-it-works** principle skill, which keeps each check real, and the **build-the-lever** principle skill, which makes the per-unit check cheap.