<!-- markdownlint-disable -->
# Discussion: What skills would most level up the agentic development system?

> Evaluating candidate skills similar to the discussion skill — meta-level capabilities that improve decision quality, not just execution quality.
> Started: 2026-03-26 | Status: 🔄 In progress

---

## Topic

The system currently has 11 skills, most of which are **execution skills** (validation pipeline, error recovery, pattern matching, consumer tracing). The discussion skill is different — it operates at the **meta level**: it improves the quality of decisions before code is written.

**Question**: Are there other skills of a similar nature — meta-level, decision-improving, or workflow-strengthening — that would materially raise the ceiling for the agentic system?

---

## Human's Position

> "are there other useful skills like the discussion skill to 'level up the game'?"

The implicit position: the discussion skill adds value beyond procedural execution skills. The hypothesis is that additional meta-skills could close remaining gaps in the workflow.

---

## State-of-the-Art Research

| Research | Finding |
|---|---|
| **Reflexion** (Shinn et al., 2023) | Agents that investigate before committing to an approach outperform agents that dive straight into execution on novel problems. The investigation narrows the search space before the high-cost execution phase. |
| **Google DORA (2024)** | Top-performing teams spend ~20% of cycle time on pre-implementation activities (spikes, ADRs, risk assessment). This correlates more strongly with deployment frequency than any post-implementation activity. |
| **Anthropic prompt engineering (2026)** | "Give Claude time to think" — structured pre-work (research, planning, decomposition) before execution produces substantially better outputs than asking for execution directly. |
| **ThoughtWorks Technology Radar (2025)** | ADRs (Architecture Decision Records) rated "Adopt" for the third consecutive year. The format is effective across team sizes and tool ecosystems. |
| **Microsoft AutoGen research (2024)** | Multi-agent systems with explicit "review your own output" loops produce 31% fewer hallucinations than single-pass agents. The self-review step is the most cost-effective quality lever. |
| **Basecamp Shape Up (Ryan Singer, 2019)** | Upfront appetite-setting (how much time is this worth?) prevents scope creep more effectively than post-implementation review. "Time boxing investigation" is the key mechanism. |

---

## Current Skill Gaps

The system is strong at **execution quality** (validation-pipeline, error-recovery, consumer-tracing) but has two underserved phases:

| Phase | Coverage | Gap |
|---|---|---|
| **Pre-investigation** | Only discussion.skill covers design decisions | No skill for technical unknowns: "can this even be built?" |
| **Execution** | Well covered | — |
| **Pre-merge** | Only typecheck + lint gates | No behavioural checklist: .only tests, console.logs, missing changeset, unresolved TODOs |
| **Institutional memory** | findings-persistence + cache.md | No structured format for capturing architectural WHY (ADRs) |
| **Complexity estimation** | None | No signal for when to activate multi-CL mode proactively |

---

## Candidate Skills Analysis

### F-1: No pre-investigation capability for technical unknowns

**Problem**: The discussion skill challenges *design* proposals (what to build, how to structure it). It does not help with *technical* unknowns: "can I even call this SDK from an App Function?", "does Grail support this aggregation?", "will this Strato component accept these props?" Agents currently either guess or MCP-storm looking for answers.

**Consequence**: Multi-session features with hidden blockers. The blocker surfaces at Step 8 of a 12-step plan.

**Fix**: A **Spike skill** — time-boxed technical investigation with a defined deliverable.

---

### F-2: No pre-merge behavioural checklist

**Problem**: typecheck + lint catch structural errors, but not behavioural ones: `test.only` left in a test file, `console.log` committed to production code, `TODO: fix this` comment without a ticket reference, changeset missing, `jest.resetAllMocks()` forgotten in a `beforeEach`. These are caught in code review — late, embarrassingly.

**Consequence**: Review agents flag recurring low-signal issues. Human reviewers develop alert fatigue.

**Fix**: A **Release Readiness skill** — automated pre-merge checklist that runs before creating a PR.

---

### F-3: No durable capture of architectural WHY

**Problem**: decisions made in `discussion.md` and `cache.md` expire with ticket context. In six months, no one knows *why* the URL params approach was chosen over Router state, or why `fetchWithCache` uses 5-minute TTL. The code embeds the *what*, never the *why*.

**Consequence**: New contributors (human or AI) repeat the same design discussions. Agent Smith can't tell the difference between a deliberate architectural choice and a deviation from best practice.

**Fix**: An **ADR (Architecture Decision Record) skill** — formats major decisions into persistent `.github/decisions/` files that survive ticket closure.

---

## Open Questions

### OQ-1: Spike vs discussion — where does the line fall?

The discussion skill handles: "should we use X or Y approach?"
The spike skill would handle: "can approach X actually be built?"

These sometimes blur. A discussion concludes "use approach X" — then a spike discovers X is impossible. Is the spike a separate invocation, or a step within the discussion skill?

**Options:**
- a) Separate skills (clean separation of concerns) — discussion for design, spike for feasibility
- b) Add a "feasibility check" step to the discussion skill — keeps it in one place
- c) Spike is a prompt, not a skill — it's a short full-cycle prompt, not composable

**Recommended**: (a) — the triggers are distinct (design question vs. technical unknown), the outputs are different (recommended approach vs. go/no-go + findings), and the audience differs (human decision vs. agent self-unblocking).

### OQ-2: Release readiness — skill or gate in validation-pipeline?

The validation-pipeline skill defines: typecheck → lint → test → coverage. Adding a behavioural checklist to it would make it longer but keep everything in one file.

**Options:**
- a) New `release-readiness.skill.md` — explicit, separately composable
- b) Add a "pre-merge" section to `validation-pipeline.skill.md` — one less file
- c) Add it as a section in `coding.agent.md` only — not a shared skill

**Recommended**: (a) — the validation pipeline is about build correctness; release readiness is about deliverable quality. They have different triggers (validation runs after every change; readiness runs once before PR). Separate concerns.

### OQ-3: ADRs — where do they live, and who writes them?

**Options:**
- a) `.github/decisions/YYYYMMDD-slug.md` — separate from tickets, permanent
- b) Inside each ticket folder `.github/tickets/<ID>/decisions/` — scoped, but ephemeral
- c) `base/knowledge/decisions.md` — a running log, not individual files

**Recommended**: (a) — ADRs are permanent institutional memory, not ticket artefacts. They outlive tickets and should be discoverable independently.

### OQ-4: Are there any other gaps not covered by these three candidates?

Current analysis covers: investigation (spike), pre-merge (release readiness), institutional memory (ADR). What remains:

- **Complexity estimation before starting** — "this ticket is M complexity, activate multi-CL mode" — but `changelist.skill.md` (QSP-44444 Step 22) partially covers this for large features. Verdict: **covered by QSP-44444, skip**.
- **Pair/self-review** — "challenge your own implementation before submitting" — but Agent Smith already does this. Verdict: **covered, skip**.
- **Onboarding skill** — "orient a new agent or human to this codebase" — but `context-triage.skill.md` already handles priority reading. Verdict: **covered, skip**.
- **Dependency vetting** — "before adding an npm package, check CVE + alternatives" — narrow enough to add as a checklist item in `release-readiness.skill.md`. Verdict: **subsume into release readiness**.

← OQ-4 RESOLVED: Three candidates are sufficient. No additional gaps justify a fourth new skill.

---

## Decisions Log

| OQ | Decision | Rationale |
|---|---|---|
| OQ-4 | Three candidates: Spike, Release Readiness, ADR | All other gaps either covered by existing/planned skills or too narrow for a dedicated skill |

---

## Recommended Approach

Three skills address real, uncovered gaps. In priority order (value vs. effort):

---

### 1. `release-readiness.skill.md` — **highest immediate value**

**Trigger**: before creating any PR or presenting work for human review.

**Checklist** (agents run this as a grep/scan pass, not manual inspection):
- [ ] No `test.only`, `describe.only`, or `test.skip` without a ticket reference
- [ ] No `console.log` in production `src/` files (warnings and errors OK)
- [ ] No `TODO` or `FIXME` comment without a Jira ticket reference in parentheses
- [ ] No `@ts-ignore` without a comment explaining why
- [ ] Changeset file present for every PR except `NOISSUE`
- [ ] `jest.resetAllMocks()` in every `beforeEach` that sets up mocks
- [ ] No `any` type in new code (search added lines only)
- [ ] All new data-testid values follow kebab-case
- [ ] No hardcoded URLs or environment-specific values in `src/`

**Output**: pass/fail report. On failure: list of violations with file + line. On pass: one-line confirmation.

**Used by**: `coding.agent.md` (end of Phase 1, before presenting to human), `agent-smith.agent.md` (as part of FAST mode structural checks).

**Effort**: ~70 lines. No new artefact types. Immediate leverage on review noise.

---

### 2. `spike.skill.md` — **highest value for complex features**

**Trigger**: when Phase 1 (requirements) identifies a technical unknown that blocks confidence in the implementation plan. Criteria for a spike:
- The implementation depends on an SDK/API that hasn't been used in this codebase before
- A DQL aggregation pattern is needed whose feasibility isn't confirmed
- A Strato component needs to be used in an undocumented way
- The estimated complexity is L or XL and a key assumption is unverified

**Procedure**:
1. Define the hypothesis: "I believe X can be achieved by doing Y"
2. Time-box to 30 minutes (1 session, no full implementation)
3. Build the minimal code needed to validate/invalidate the hypothesis
4. Write findings: hypothesis, result (validated/invalidated), code sample, recommendation
5. Output to `.github/tickets/<ID>/spike.md`
6. Gate: if hypothesis **invalidated**, loop back to requirements.agent with the new constraint before proceeding

**Output**: `spike.md` with verdict (GO / NO-GO / PIVOT). The implementation plan cannot proceed past a technical unknown until the spike resolves it.

**Used by**: `requirements.agent.md` (when an unknown is identified during planning), `coding.agent.md` (as a fallback for stuck investigation).

**Effort**: ~80 lines. One new artefact type (`spike.md`). High value for novel features.

---

### 3. `adr.skill.md` — **highest long-term institutional value**

**Trigger**: when a decision is made during discussion or requirements that:
- Affects the overall architecture (a new pattern, a new layer, a structural change)
- Chooses between two or more viable alternatives
- Reverses a prior decision
- Would not be obvious to a new contributor reading the code

**Format**: based on [MADR (Markdown Architectural Decision Records)](https://adr.github.io/madr/) — the most tool-friendly ADR format.

```markdown
# ADR-NNN: <decision title>

**Date**: YYYY-MM-DD  
**Ticket**: QSP-XXXXX  
**Status**: Accepted

## Context

<Why this decision needed to be made. The forces at play.>

## Decision

<What was decided.>

## Alternatives Considered

| Alternative | Pros | Cons | Why rejected |
|---|---|---|---|

## Consequences

**Positive**: ...
**Negative**: ...
**Neutral**: ...
```

**Output**: `.github/decisions/NNN-slug.md`. The NNN is sequential.

**Used by**: `discussion.skill.md` (after all OQs are resolved, write ADR for significant decisions), `requirements.agent.md` (after approval, write ADRs for architectural decisions in the spec).

**Effort**: ~60 lines. New directory `.github/decisions/`. The format is simple and well-understood (MADR is an industry standard).

---

## Implementation Priority

| Skill | Value | Effort | Priority |
|---|---|---|---|
| `release-readiness.skill.md` | High — catches recurring review noise before review | Low (~70 lines) | **1 — implement in QSP-44444 or next ticket** |
| `spike.skill.md` | High — prevents mid-feature blockers | Medium (~80 lines) | **2 — next ticket after QSP-44444** |
| `adr.skill.md` | Medium now, high long-term | Low (~60 lines) | **3 — can be bundled with either above** |

