authoring-software-leverage-points

name	authoring-software-leverage-points
description	Use when authoring or refining any skill in the software-leverage-points plugin (the 17 SLPs, the 3 operator skills, operator-synthesis references, or L2 templates). Captures the architectural model, the section shape per skill type, the cross-reference and continual-improvement conventions, and the house rules so authoring stays consistent.

Authoring Software Leverage Points

Overview

This skill is the canonical authoring contract for this repo. Read it before adding or refining any skill. It encodes:

• The three-layer model (L1 plugin generic, L2 repo-specific, L3 active reviews) the plugin rests on.
• The structural difference between principle skills (the 17 SLPs) and procedural skills (the 3 operator skills: software-leverage-review, skill-builder, skill-auditor).
• The cross-reference conventions every SLP follows: canonical relative-link form, bidirectional symmetry, terminology ("skill", not "lens" or "SLP" in prose).
• The Continual improvement footer every SLP and operator skill carries so downstream agents know where to file improvements.
• The L2 skill template skill-builder emits, including ## Maturity Assessment and ## Growth Direction.
• The house rules: em-dash hygiene, citation discipline, audit-script gates, dated technology recommendations.

Core principle: Each kind of skill in this plugin has a defined shape. Don't mix shapes; don't drift them; consult this skill before authoring.

When to Use

• Authoring a new software leverage point (e.g., adding an 18th).
• Refining an existing SLP based on user feedback or evals.
• Authoring or refining one of the 3 operator skills.
• Authoring or refining an operator-synthesis reference doc under skills/software-leverage-review/references/.
• Adding or refactoring cross-references between skills.
• Updating the L2 template that skill-builder emits.
• Reviewing an agent-authored skill to check it conforms.

Skill Types and Layers

The plugin has two skill types and three layers. The two axes are orthogonal: type is what kind of thing the skill is (substance vs meta); layer is where the skill lives (plugin, target repo, or runtime).

Two types

Principle skills (substance): 17 software leverage points. Each captures the durable patterns, red flags, and growth examples for one concern. Principle skills are consulted, not invoked: they are content the operator skills read during a review. They have no Workflow section. Three of the SLPs (dry, software-complexity, principles-and-patterns) also have peer operator-synthesis reference docs under skills/software-leverage-review/references/; those are companion artifacts for the orchestrator's synthesis pass, not separate skills.

Operator skills (meta): software-leverage-review, skill-builder, skill-auditor. Three procedural skills that consume principle skills, dispatch subagents, and emit findings. Each has a Workflow. Operator skills are generic (in this plugin only); they don't have repo-specific variants.

Three layers

Layer	Principle skills	Operator skills
L1: Generic in plugin	skills/<lp>/SKILL.md (17 SLPs)	skills/{software-leverage-review,skill-builder,skill-auditor}/SKILL.md
L2: Repo-specific	<target>/.claude/skills/<lp>/SKILL.md (generated by skill-builder; includes Maturity Assessment + Growth Direction)	n/a (operators stay generic and parameterize per invocation)
L3: Active reviews	(consumed by reviews; no separate file)	Invoked at review time; fan out subagents that consume L2 principle skills, fall back to L1 for principles

L1 and L2 are file artifacts; L3 is runtime only. When you author a new skill, decide both: type (principle or operator) and layer (plugin or runtime-bootstrapped). Each combination has a defined shape, captured below.

SLP Skill Structure (principle-doc shape)

For each of the 17 software leverage points, the SKILL.md is a principle doc: a body of named principles, anti-patterns, and growth examples that an operator skill consults during a review. It is not invoked as a function and does not have a workflow of its own.

---
name: <lp-name>
description: Use when reviewing <lp-name> concerns: <short list of axes>
---

# <Title>

## Overview                 (intent + Core principle one-liner)
## Core Principles          (the durable patterns this skill enforces)
## Red Flags - STOP         (concrete anti-patterns the skill surfaces)
## Rationalization Prevention   (table: Excuse / Reality)
## Key Patterns             (side-by-side good/bad scenarios)
## Why This Matters         (the consequence of ignoring the skill)
## Growth examples          (POC, growing, production, safety-critical)
## References & rationales  (named sources, paired with the principle each backs)
## Suggested technologies (as of YYYY-MM-DD)   (dated, illustrative, not prescriptive)
## Continual improvement    (GitHub link to the file + pointer to the chassis skill)

Notably absent: Input, Workflow, Output, schema reference. SLPs do not have "workflows" because they are not invoked as procedures. The operator skills carry the procedure; SLPs carry the content the procedure consults.

Authoring rules for principle skills

Three rules apply to every principle SLP, learned by refining testing first and forward-applied to subsequent skill authoring:

1. Growth examples are tech-agnostic. Specific tools and frameworks belong only in ## Suggested technologies (as of YYYY-MM-DD). Growth examples describe the practices and patterns that mature across maturity stages; tools change underneath those patterns. Naming a specific tool in a growth example creates drift the moment that tool falls out of fashion.

2. Principles must scope themselves. When a principle applies to a subset of the SLP's surface, the principle's heading or first sentence states the scope explicitly. Example: FIRST applies only to unit tests; integration and end-to-end tests inherit only a subset. Without explicit scoping, the principle over-claims and findings drawn from it become wrong.

3. Multiple-valid-approach principles state the choice rule. When more than one good approach exists for a concern, the principle articulates the options and requires within-project consistency rather than picking one arbitrarily. The red flag is "no stated convention," not "did not pick approach X." Example: test locality, where mirroring under tests/ and co-locating with source are both valid; the SLP's job is to require a chosen-and-consistent approach, not to dictate which.

L2 Skill Structure (skill-builder output)

When skill-builder instantiates an SLP into a target repo, the L2 SKILL.md adds two sections that capture where this repo is and where its next maturity step would lead:

---
name: <lp-name>
description: Use when reviewing <lp-name> concerns in <repo-name>
---

> **Generic principles:** see L1 meta-skill at <plugin>/skills/<lp>/SKILL.md

## Repo Context             (language, framework, layout, observed facts)
## Maturity Assessment      (Current level + Signals + Last reviewed)
## Growth Direction         (Natural next step + Trigger + Don't bother yet)
## Repo-Specific Checks     (calibrated to current maturity)
## Workflow                 (apply repo-specific checks; defer to L1; emit findings per output schema)

L2 skills are journey artifacts: they describe the repo's current stage and document the path forward. skill-auditor watches them for drift.

Operator Skill Structure (procedural shape)

The 3 operator skills are procedural. They invoke things, dispatch subagents, emit structured output.

---
name: <operator-name>
description: Use when <triggers>
---

# <Title>

## When to Use
## When NOT to Use
## Input                (named parameters)
## Workflow             (numbered, executable steps)
## Output               (conforms to skills/software-leverage-review/output-schema.json)
## References           (relevant prompt files, schema docs, lens refs)

Operator skills MAY include ## Calibrate severity to maturity and similar procedural extensions, but they keep the Input/Workflow/Output spine.

Operator Flows

The 3 operator skills serve 5 distinct use cases. Authors should know which flow they are touching and which operator owns it. Mixing flows across operators is a smell.

#	Flow	Operator	Triggers when...
1	Code review using L2 skills	software-leverage-review	A plan, PR, or codebase needs review; L2 skills are present.
2	Bootstrap L2 skills (first-time setup)	skill-builder	The target repo has no .claude/skills/<lp>/SKILL.md yet. Analyze the code, template from L1, ship each L2 with Maturity Assessment + Growth Direction.
3	L2 drift detection	skill-auditor	Code has changed since the L2 was last reviewed; Repo Context or Maturity Assessment may be stale.
4	Maturity update	skill-auditor flags, skill-builder updates	The target outgrew its L2's claimed level (POC now has CI and external users; production now has safety-critical surface; etc.).
5	Growth direction realization	software-leverage-review or skill-auditor	The L2's Growth Direction "next step" is overdue: the target hit the trigger conditions but did not address the step.

Flows 2 and 4 are L2 creation/update flows. Flows 1 and 5 are L2 consumption flows. Flow 3 is the watchdog that connects them.

The L2 SKILL.md is therefore a journey artifact: created at flow 2, consumed at flows 1 and 5, watched at flow 3, updated at flow 4. When authoring or refining any skill, ask which flow(s) the change affects; that decides which operator skill needs alignment.

Skill-local resources (progressive disclosure, organized by topic)

A skill MAY ship additional artifacts alongside its SKILL.md: deep-dive docs, example scripts, fixtures, schemas, templates. The underlying principle is progressive disclosure: anything pulled out of the principle doc is a deeper layer the reader should be able to descend into when they need it, and the structure should make that descent obvious without rummaging.

Organize by topic, not by file type. When extracting deep-dive material from a SKILL.md, give the topic its own subdirectory under the skill, and put everything for that topic inside (doc, examples, scripts). This keeps a feature cohesive at the directory level so a reader following a single link finds the full deep-dive in one place.

✅ skills/architecture/fitness-functions/
       README.md          (the deep-dive doc)
       examples/          (example fitness functions)
       scripts/           (runnable templates)

❌ skills/architecture/
       references/fitness-functions.md
       examples/fitness-functions-coupling.py
       scripts/fitness-functions-runner.sh

The second layout fragments one topic across three sibling directories and forces the reader to look in three places to assemble the picture.

Rules:

• The SKILL.md MUST link to every topic subdirectory it owns (typically by linking the README.md inside). Resources unreferenced from SKILL.md are dead weight and rot silently.
• Use relative paths in every link, at every level. scripts/audit.sh validates link integrity, so broken references fail CI.
• Links chain by progressive disclosure: SKILL.md links to <topic>/README.md; the topic README.md links to its own examples/, scripts/, fixtures, or sub-topics; each example or script links back up to its README.md (and through it, the SLP) in a top-of-file comment. A reader entering at any level can descend into detail and ascend to context without rummaging.
• Inside example files, top-of-file comments cite the SLP by relative path (e.g. ../../../SKILL.md) and name the principles the example illustrates. Files unreferenced from prose are easy to delete by accident; files that cite their parent are self-orienting.
• Use README.md as the topic doc filename so the directory renders cleanly on GitHub and matches reader expectations.
• Topic subdirectories are for substantive deep-dives (event sourcing, fitness functions, vertical slice patterns, ADR templates with examples, typed-config registries with runnable code). Single-paragraph notes belong inline in the SKILL.md.
• Operator-synthesis references (the peer reference docs for dry, software-complexity, and principles-and-patterns) are an exception: they live under skills/software-leverage-review/references/ because the operator's synthesis pass consumes them differently from the SKILL.md content. They are not separate skills; they share the SKILL.md material in a shape tailored to the orchestrator.

This is the mechanism by which an SLP can stay tight (principle-doc shape) while still owning longer-form material a reviewer or agent may need to consult.

Cross-references between skills

Skills cite each other constantly. The convention is mechanical: one canonical link form, bidirectional symmetry, and a regex-checked validator that catches drift. Get this wrong and the validator (scripts/check-backlinks.sh, also wrapped by audit.sh Check 5) fails the build.

Canonical form

When SKILL A cites SKILL B, write:

the [`B`](../B/SKILL.md) skill

Three properties matter:

1. The skill name in backticks. `B` makes the cited name greppable and visually distinct from prose.
2. A relative markdown link to the target SKILL.md. Relative paths render correctly on GitHub, in the Claude Code skill viewer, and in IDEs that resolve local links. Absolute paths and bare names do not all three.
3. The word "skill" after the link. This disambiguates the citation from a topical mention of the same name as a concept (e.g. "a testing framework" is topical; "the testing skill" is a citation).

A typical "Cross-reference:" sentence looks like:

Cross-reference: the [`testing`](../testing/SKILL.md) skill carries the test-quality side of this discipline; the [`types`](../types/SKILL.md) skill carries the static side.

Terminology: "skill", not "lens" or "SLP"

In prose, every cross-reference reads as "the <name> skill." Earlier drafts used "lens" or "SLP"; both have been retired because they confuse downstream readers (the same artifacts are interchangeably called skills, leverage points, or both, and "lens" added a fourth term that did not pull its weight). The validator still recognizes the legacy phrasings (`B` lens, `B` SLP) for transition safety, but new authoring uses "skill."

When a sentence refers to the document itself ("this lens covers..."), write "this skill covers..." instead. When the heading callout mentions the operator-synthesis reference doc, the heading is **Skill cross-reference.**, not **Lens cross-reference.**.

Bidirectional symmetry is enforced

If A cross-references B, then B must cross-reference A. The validator builds the directed graph from the canonical form (and the legacy forms, plus path matches skills/B/ and ../B/SKILL.md) and reports any one-way edge.

When you add a cross-reference, plan the back-edge in the same edit. Natural shapes for the back-edge:

• A "Cross-reference:" sentence inside the most relevant principle in the target skill, mirroring the framing in the source. Two sentences total across both files is enough; the framings should differ slightly so each file reads coherently to its own reader.
• An inline mention inside a related principle when the relationship is structural (e.g., architecture mentions fitness functions; types mentions the same pattern applied to type bypasses; both files name the connection from their own angle).

If the back-edge is genuinely awkward to write because the relationship is one-way (an operator skill consuming an SLP, not the reverse), the answer is don't cite it from prose. Operator skills are excluded from the symmetry check because they legitimately consult SLPs without being cited back.

What does and does not count as a cross-reference

The validator counts any of these as A -> B:

• `B` skill (canonical)
• `B` lens or `B` SLP (legacy)
• skills/B/ (absolute-style path; appears in some markdown link targets)
• ../B/SKILL.md (relative-link path; the target must be SKILL.md specifically, so deep-dive subdir links like ../B/topic/README.md are not counted)

Bare topical mentions (`B` without one of those suffixes, or unbacticked uses of the word) do not count. This keeps SLPs free to discuss adjacent concepts by name without forcing a back-edge.

Repairing asymmetries

When audit.sh reports A -> B (missing back-edge B -> A):

1. Open both files.
2. Decide whether the relationship is genuine. If it is, add a one-sentence back-edge to B.
3. If the relationship is incidental (the original cross-reference was stale or topical), remove it from A instead.
4. Re-run bash scripts/check-backlinks.sh.

Never silence the validator by editing the regex; the regex is the contract.

Continual improvement footer

Every SKILL.md under skills/ ends with a ## Continual improvement section pointing downstream agents at the canonical source for that file. The section is small, static, and exists for one reason: when an agent reading the skill notices an improvement, it needs to know where to file it.

Which files carry the footer

File path	Carries footer?
skills/<slp>/SKILL.md (the 17 SLPs)	Yes
skills/{software-leverage-review,skill-builder,skill-auditor}/SKILL.md (operator skills)	Yes
.claude/skills/<meta>/SKILL.md (this skill, maintaining-software-leverage-points)	No

The meta-skills under .claude/skills/ are internal to the plugin's own maintenance loop. They are not consumed by downstream agents reviewing other people's code, so a "where to file improvements" footer would be noise.

Template

For SLPs and operator skills (the relative path back to the chassis skill is identical because both live two levels deep under repo root):

## Continual improvement

This skill is maintained at:
https://github.com/syntropic137/software-leverage-points/blob/main/skills/<name>/SKILL.md

To improve it, edit the file directly and follow the chassis discipline in [`maintaining-software-leverage-points`](../../.claude/skills/maintaining-software-leverage-points/SKILL.md): regenerate catalogs, run `just qa`, then commit.

Replace <name> with the directory name. The GitHub URL uses the main branch and the syntropic137/ org. If the repo or default branch changes, update the template here and re-sweep.

When adding a new skill

1. Author the SKILL.md following the principle-doc or operator shape.
2. Add cross-references with their back-edges in the same commit (see above).
3. Append the Continual improvement footer using the template above.
4. Run just regenerate-catalogs then just qa.
5. Commit.

The maintaining-software-leverage-points skill carries the chassis-side detail (which scripts run, when, and why). This skill carries the authoring-side detail (what shape the content takes, including the link conventions and the footer).

House Rules

1. No em-dashes anywhere in tracked content. The project rule (CLAUDE.md) and scripts/audit.sh both enforce this. Use a colon, comma, or restructure.
2. bash scripts/audit.sh must pass before every commit. The script verifies LP count consistency, version parity across vendor manifests, link integrity, and the em-dash rule.
3. Citations paired with rationale. Every red flag in an SLP must trace back to a named source in the ## References & rationales section. Decorative citations are not allowed; each citation must do work.
4. Suggested technologies are dated. Format: ## Suggested technologies (as of YYYY-MM-DD). The line under the heading explicitly notes that these go stale and the date is the "as-of." The principles outlast the technologies.
5. Never inline multi-line scripts in any tracked markdown (SKILL.md, deep-dive READMEs, lens references). Extract to a standalone file under the skill's scripts/ (or a topic-local scripts/) and cite by relative path. Inline snippets are tolerable for one-or-two-line illustrations; anything longer becomes an untested code copy that drifts. Prefer cross-platform script languages (Python, Node, or a runtime native to the SLP's domain) over bash, since example scripts are read and adapted by contributors on different operating systems. An isolated, testable script in any language beats an inline bash block, but "isolated and testable in a portable language" is the target.
6. Conventional commits. feat(skills): ..., feat(operators): ..., fix(...): ..., docs(...): ..., eval(NNN): .... Match existing history.
7. No marketplace-targeted polish in skill content. The skills serve agents, not marketplace browsers. Marketing-toned descriptions live in marketplace.json, not in SKILL.md frontmatter.
8. Maturity awareness, not maturity gates. Findings calibrate severity to the target's stage. They do not block work for being at an earlier stage.
9. Cross-references use the canonical relative-link form the [`B`](../B/SKILL.md) skill. No "lens" or "SLP" terminology in new prose.
10. Cross-references are bidirectional. When you add A -> B, add B -> A in the same commit. scripts/check-backlinks.sh (run by just qa) fails the build on asymmetry.

Red Flags - STOP

Mistakes to catch in SLP authoring:

• An SLP has an ## Input or ## Workflow section. (It should not. Move the procedure to the operator skill.)
• A red flag in the SLP has no paired rationale citation in ## References & rationales.
• A "Suggested technologies" section is undated.
• Citations are decorative, not load-bearing (citing a famous book whose ideas don't actually appear in the SLP's checks).
• Em-dashes or en-dashes anywhere (Unicode U+2014 or U+2013); use a colon, comma, or restructure.
• An L2 skill is missing ## Maturity Assessment or ## Growth Direction.
• An operator skill is consulting an SLP "as a function" rather than reading its principles.
• The SLP description is generic ("Use when reviewing testing concerns" with no axes named); auto-trigger has no signal to match.
• A cross-reference uses the `B` lens or the `B` SLP (legacy phrasings); use the [`B`](../B/SKILL.md) skill instead.
• A cross-reference is one-way: A cites B but B does not cite A. The audit fails on asymmetry; add the back-edge or remove the original.
• A cross-reference uses an absolute path or a bare name without a relative markdown link. Both render incorrectly in some viewers; use the canonical form.
• An SLP or operator SKILL.md is missing the ## Continual improvement footer.
• A meta-skill under .claude/skills/ was given the Continual improvement footer; it does not belong there.

Rationalization Prevention

Excuse	Reality
"The SLP needs a workflow so the agent knows what to do"	The operator skill carries the workflow; the SLP carries the principles the workflow consults
"We can fix the em-dash later"	The audit script blocks the commit; fix it now
"These tools are obviously the right ones"	Frameworks shift; the date is the receipt
"Adding a citation makes it look rigorous"	A citation that doesn't shape a check is decorative; remove it
"L2 doesn't need Maturity Assessment for a small repo"	Small repos grow; the L2 captures the journey, not just the snapshot
"I'll skip audit.sh just this once"	The drift findings the eval suite catches are exactly the failures we are preventing
"I'll add the back-edge in a follow-up PR"	The validator fails the current PR; add the back-edge in the same edit
"Calling them lenses reads better"	Three terms for one thing (skill, leverage point, lens) is one too many; pick "skill" in prose and stay there
"I'll skip the Continual improvement footer; it's boilerplate"	It is the only signal a downstream agent has for where to file an improvement; the boilerplate is the feature

Why This Matters

Without this skill, every authoring session reinvents conventions. SLPs drift toward inconsistent shapes, citations become decorative, em-dashes leak in, and the principle/procedural split blurs. The plugin then loses the property that made the eval scores climb: each SLP is a coherent lens, distinct from its neighbors, calibrated to the target.

This skill is the single source of authoring truth. Read it. Apply it. Future maintainers (humans and agents) thank you.

References

• scripts/audit.sh enforces the mechanical subset of these rules (em-dash hygiene, link integrity, count consistency across docs, manifest version parity).
• skills/software-leverage-review/output-schema.json is the structured-output contract that every finding conforms to (emitted by the operator skills, not the SLPs themselves).
• skills/software-leverage-review/SKILL.md shows the procedural-skill shape in practice.
• Any existing SLP under skills/<lp>/SKILL.md shows the principle-doc shape in practice (testing, logging, architecture are good starting points).