Skip to content

Commit a7cf24a

Browse files
rodion-mclaude
rodion-m
and
claude
committed
Add use cases, thinking-verb router, and composition guidance to SKILL.md
Improve agent navigation by adding intent-based routing (thinking verbs mapped to FPF sections), use cases framing FPF as a thinking accelerator, multi-section composition guidance, and a maintenance methodology for spec updates. Changes: - SKILL.md: use cases, thinking-verb router (Step 1), composition guidance (Step 4), role-adaptive starter prompt, rewritten INDEX with verb-led descriptions - FPF-SKILL-UPDATE-GUIDE.md: repeatable methodology for updating SKILL.md when FPF spec changes, including FPF self-audit checklist - README.md: two-step update process linking to the guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 49bc6ed commit a7cf24a

3 files changed

Lines changed: 196 additions & 34 deletions

File tree

‎FPF-SKILL-UPDATE-GUIDE.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# FPF Skill Index Update Guide
2+
3+
Methodology for maintaining SKILL.md when the FPF specification changes.
4+
Discovered by applying FPF to its own skill file — dog-fooding the framework.
5+
6+
## When to update
7+
8+
- New sections or sub-sections added to FPF
9+
- Sections renamed, merged, or reorganized
10+
- New FPF patterns introduced that serve a distinct thinking need
11+
- Existing router entries found to misroute (validated against real usage)
12+
- Description trigger phrases no longer match how users actually invoke FPF
13+
14+
Per B.3.4 (Evidence Decay), the SKILL.md carries epistemic debt whenever the spec
15+
evolves and the skill file doesn't. The Section INDEX provides a structural fallback,
16+
but a stale thinking-verb router silently degrades navigation quality.
17+
18+
## What to update (checklist)
19+
20+
### 1. Description field (YAML frontmatter)
21+
22+
The description decides WHETHER the skill triggers at all. It must include:
23+
- What FPF does (capability)
24+
- When to use it (trigger phrases the user might say)
25+
- When NOT to use it (negative triggers to prevent false activation)
26+
27+
When adding new FPF capabilities, add corresponding trigger phrases.
28+
Keep under 1024 characters. No XML angle brackets.
29+
30+
### 2. Use cases section
31+
32+
These are broad cognitive situations — "thinking accelerator" framing, not section lookups.
33+
Each use case should be a problem a human recognizes, not an FPF-internal concept.
34+
35+
Ask: "Would a user who has never heard of FPF describe their problem this way?"
36+
If yes, it's a good use case. If it requires FPF vocabulary to understand, it's too internal.
37+
38+
### 3. Thinking-verb router (Step 1 table)
39+
40+
This is the core navigation improvement. Each row maps a **thinking verb** to a starting point.
41+
42+
To add a new row:
43+
1. Identify the thinking need the new FPF content serves (what does it help the user DO?)
44+
2. Name it with a bold verb: **Decompose**, **Evaluate**, **Unify**, etc.
45+
3. Point to the specific section AND sub-section (e.g., "08 Part C -> C.18 NQD")
46+
4. Check for overlap with existing rows — merge if the thinking need is the same
47+
48+
To validate a row:
49+
- Simulate a user query that should trigger this row
50+
- Follow the path: does the `_index.md` of the target section lead to a useful sub-section?
51+
- If the path dead-ends or leads somewhere unexpected, the row is wrong
52+
53+
Principles (from the FPF audit):
54+
- **Strict Distinction (A.7)**: Each row should serve a distinct thinking need. If two rows feel interchangeable, they're probably a category error — find the real distinction or merge them.
55+
- **Cognitive Elegance (P-1)**: Resist growing the router beyond ~20 entries. If it gets longer, some entries probably overlap. An agent pattern-matches against the table — more rows means slower matching and more ambiguity.
56+
- **WLNK (B.3)**: One wrong row degrades trust in the whole router. Validate carefully.
57+
58+
### 4. Section INDEX table
59+
60+
Structural reference. Must stay in sync with actual `sections/` folders.
61+
62+
Each "When to use" cell should lead with a **bold thinking verb** so even the structural
63+
table doubles as intent-based navigation. Pattern: `**Verb**: what's inside`.
64+
65+
When sections are added/removed:
66+
1. Add/remove the row
67+
2. Write a thinking-verb description
68+
3. Check if the new section should also appear in the thinking-verb router (Step 1)
69+
70+
### 5. Composition guidance (Step 4)
71+
72+
Update if:
73+
- New patterns create novel cross-section composition needs
74+
- Users consistently struggle to synthesize findings from certain section combinations
75+
- New category-error patterns are discovered (add to the A.7 check)
76+
77+
The natural synthesis order (decompose -> evaluate -> resolve) should remain stable
78+
unless FPF's reasoning architecture fundamentally changes.
79+
80+
## How to validate (FPF self-audit)
81+
82+
After updating, run these checks against the FPF patterns that matter most for a navigation artifact:
83+
84+
| FPF Pattern | Check |
85+
|---|---|
86+
| **Bounded Context (A.1.1)** | Does the SKILL.md have clear entry/exit semantics? Does the router bridge user-intent context to FPF-spec context without collapsing them? |
87+
| **Strict Distinction (A.7)** | Are use cases (admission) and router (navigation) still clearly separated? Does any row conflate two different thinking needs? |
88+
| **Trust & Assurance (B.3)** | Can each router row be grounded in actual spec content? Would following the path produce a useful result? |
89+
| **Multi-View (E.17)** | Does the router serve different user roles (engineer, manager, researcher) without being locked to one view? |
90+
| **Epistemic Debt (B.3.4)** | Are there sections in the INDEX that aren't reachable from the router? If so, is that intentional (not every section needs a router entry) or an omission? |
91+
| **Composition (B.1)** | If new sections are added, does Step 4 still give adequate synthesis guidance? Are there new cross-section patterns to document? |
92+
| **Cognitive Elegance (P-1)** | Is the file still compact? Growth should be justified by navigation value, not completeness for its own sake. |
93+
94+
## Process summary
95+
96+
```
97+
1. Identify what changed in the FPF spec
98+
2. For each change, ask: "What thinking need does this serve?"
99+
3. Update the relevant SKILL.md component (description / use cases / router / INDEX)
100+
4. Run the FPF self-audit (table above)
101+
5. Test with simulated user queries
102+
```

‎README.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,15 +52,29 @@ The agent reads `_index.md` first, picks the right sub-section file, and loads o
5252
| 19 | Part J — Indexes | 0 |
5353
| 20 | Part K — Lexical Debt | 2 |
5454

55-
## Regenerating sections
55+
## Updating after FPF spec changes
5656

57-
If the upstream FPF spec changes, pull the submodule and re-run the splitter:
57+
When the upstream FPF specification changes, two things need updating:
58+
59+
### 1. Regenerate section files
60+
61+
Pull the submodule and re-run the splitter to rebuild the `sections/` hierarchy:
5862

5963
```bash
6064
git submodule update --remote
6165
python3 scripts/split_spec.py
6266
```
6367

68+
### 2. Update SKILL.md navigation
69+
70+
The section files are raw content — `SKILL.md` is the navigation layer on top.
71+
After regenerating, review whether the thinking-verb router, use cases, or Section INDEX
72+
in `SKILL.md` need updating to reflect new, changed, or removed content.
73+
74+
See **[FPF-SKILL-UPDATE-GUIDE.md](FPF-SKILL-UPDATE-GUIDE.md)** for the full
75+
methodology: what to check, how to validate router entries, and how to run an FPF self-audit
76+
on the skill file itself.
77+
6478
## Credits
6579

6680
- **FPF specification**: [Anatoly Levenchuk](https://github.com/ailev) — [github.com/ailev/FPF](https://github.com/ailev/FPF)

‎SKILL.md‎

Lines changed: 78 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: fpf-simple
3-
description: "First Principles Framework (FPF) — transdisciplinary reasoning architecture for systems engineering, knowledge coordination, and mixed human/AI teams. Use when the user mentions FPF, first principles, bounded contexts, SoTA packs, concept unification, assurance calculus, or FPF Parts A-K. Not for general philosophy or Agile unrelated to FPF."
3+
description: "First Principles Framework (FPF) — transdisciplinary reasoning architecture that accelerates rigorous thinking for systems engineering, knowledge coordination, and mixed human/AI teams. Use when the user mentions FPF, first principles framework, bounded contexts, holonic decomposition, SoTA packs, concept unification, assurance calculus, trust scores, epistemic scoring, or FPF Parts A-K. Not for general philosophy or Agile unrelated to FPF."
44
license: MIT
55
---
66

@@ -11,51 +11,97 @@ written in human- and machine-readable pseudo-code. FPF turns raw intelligence (
1111
into organisationally usable reasoning: explicit bounded contexts, auditable artefacts, multi-view
1212
descriptions, and disciplined hand-offs between specialised actors.
1313

14-
## How to use
14+
## Use cases
1515

16-
The spec is split into `sections/` with a two-level hierarchy:
16+
Use FPF whenever you need to think more rigorously than the situation's default.
1717

18-
1. Find the relevant Part from the INDEX below.
19-
2. Read its `_index.md` to see the list of sub-sections with descriptions.
20-
3. Read only the specific sub-section file you need.
21-
4. Apply FPF patterns using plain language; introduce FPF-internal names only when they add precision.
18+
- Decompose a messy, cross-domain problem into parts that can be reasoned about independently
19+
- Make a high-stakes decision with incomplete evidence — and know what evidence is still missing
20+
- Get a mixed team to reason together without vocabulary collisions or hidden assumptions
21+
- Audit whether a conclusion is well-founded or just plausible
22+
- Transfer an insight across domains without losing precision or introducing category errors
23+
- Structure a proposal that must survive scrutiny from multiple expert perspectives
24+
- Generate alternatives systematically instead of anchoring on the first idea
25+
- Define what "better" means before comparing options
2226

23-
IMPORTANT: Always start by reading `_index.md` of the relevant section folder —
24-
it lists all sub-sections with line counts and descriptions so you can pick the right file
25-
without loading thousands of lines.
27+
## How to navigate
2628

27-
## Starter prompt
29+
The use cases above help decide WHETHER to invoke FPF. The router below decides WHERE to go once invoked.
30+
31+
### Step 1 — Match the thinking need to a starting point
32+
33+
| What you need to do | Start here |
34+
|---|---|
35+
| **Decompose** a complex whole into bounded parts | 04 Kernel → A.1 Holons, A.1.1 Bounded Contexts, A.14 Mereology |
36+
| **Assign** roles and responsibilities | 04 Kernel → A.2 Roles, A.15 Role-Method-Work Alignment |
37+
| **Set boundaries** on what statements mean | 05 Signature Stack → classify as definitions, gates, duties, or evidence |
38+
| **Prevent category errors** (role vs. function, method vs. work) | 06 Constitutional Principles → A.7 Strict Distinction |
39+
| **Evaluate confidence** in a claim or artifact | 07 Part B → B.3 Trust & Assurance; 08 Part C → C.2 F-G-R scoring |
40+
| **Compose** parts into wholes preserving properties | 07 Part B → B.1 Gamma algebra; 08 Part C → C.13 Compose-CAL |
41+
| **Reason through** a problem systematically | 07 Part B → B.5 Reasoning Cycle, B.5.2 Abductive Loop |
42+
| **Generate alternatives** / explore solution space | 08 Part C → C.18 NQD Open-Ended Search, C.19 Explore-Exploit |
43+
| **Measure and compare** options rigorously | 06 A.V → A.17-A.19 Characteristics & CSLC; 08 Part C → C.16 MM-CHR |
44+
| **Score knowledge** quality (formality, scope, reliability) | 08 Part C → C.2 KD-CAL, C.2.2 Reliability, C.2.3 Formality |
45+
| **Resolve conflicts** across stakeholders or values | 09 Part D → Ethics & Conflict |
46+
| **Unify vocabulary** across teams or domains | 13 F.I Context of Meaning → 14-15 UTS tables → 20 Lexical Debt |
47+
| **Document** for multiple audiences | 11 E-I Constitution → E.17 Multi-View Publication Kit |
48+
| **Survey a discipline** and build a reusable toolkit | 16 Part G → SoTA Packs, TraditionCards, OperatorCards |
49+
| **Trace provenance** of a claim | 06 A.V → A.10 Evidence Graph; 16 Part G → G.6 Provenance Ledger |
50+
51+
For complex problems, follow paths across multiple sections — the router shows where to start, not where to stop.
52+
53+
### Step 2 — Read the _index.md, then the sub-section
54+
55+
1. Open the `_index.md` of the target section folder — it lists all sub-sections with line counts and descriptions.
56+
2. Read only the specific sub-section file you need.
57+
3. Do NOT load entire sections. Pick the narrowest file that serves the user's question.
58+
59+
### Step 3 — Apply in plain language
60+
61+
Use plain language for the user. Introduce FPF-internal names (U.Holon, Gamma, F-G-R)
62+
only when they add precision the user needs.
63+
64+
### Step 4 — Compose findings across sections
65+
66+
When a problem draws from multiple sections:
67+
68+
1. State each pattern's contribution in one line (e.g., "Bounded Contexts gives us the parts; Trust Calculus scores our confidence in each").
69+
2. If patterns from different sections appear to conflict, check for category errors via A.7 Strict Distinction — the conflict is usually a level confusion (role vs. function, method vs. work), not a real contradiction.
70+
3. Synthesize in natural order: decomposition first (what are the parts?), then evaluation (how confident are we?), then resolution (what do we do about gaps?).
71+
4. Do not just list FPF patterns — weave them into a coherent answer to the user's actual question.
72+
73+
## Starter prompt (example — adapt to the user's actual role and need)
2874

2975
> You have the FPF specification loaded.
30-
> Help me structure your project / problem / programme.
76+
> Help me structure my project / problem / programme.
3177
> Use plain language for an engineer-manager.
3278
> Propose: (1) bounded contexts / specialisations, (2) decision criteria, (3) key alternatives,
3379
> (4) hand-offs, and (5) missing evidence or tests before commitment.
3480
> Introduce internal FPF names only when they add precision.
3581
3682
## Section INDEX
3783

38-
Each entry is a folder. Read its `_index.md` first, then pick the sub-section file you need.
84+
Structural reference. Each entry is a folder — read its `_index.md` first, then pick the sub-section.
3985

40-
| # | Section | Sub-sections | When to use |
86+
| # | Section | Sub | When to use |
4187
|---|---------|:---:|-------------|
4288
| 01 | [Title page](sections/01-first-principles-framework-core-conceptual-specification/_index.md) | 0 | Authorship, version date, top-level identity. |
43-
| 02 | [Table of Content](sections/02-table-of-content/_index.md) | 0 | Navigate the spec, locate a pattern, understand inter-section dependencies. |
44-
| 03 | [Preface](sections/03-preface/_index.md) | 17 | Onboarding to FPF; choosing a reading path by role. |
45-
| 04 | [Part A — Kernel Architecture](sections/04-part-a-kernel-architecture-cluster/_index.md) | 19 | Core ontological building blocks: holons, bounded contexts, roles, transformers, method/work separation, generative search. |
46-
| 05 | [A.IV.A — Signature Stack & Boundary](sections/05-cluster-a-iv-a---signature-stack-boundary-discipline/_index.md) | 18 | System boundaries, APIs, protocols — classifying statements as definitions, gates, duties, or evidence. |
47-
| 06 | [A.V — Constitutional Principles](sections/06-cluster-a-v---constitutional-principles-of-the-kernel/_index.md) | 29 | Prevent category errors: role vs. function, method vs. work, holon vs. system vs. episteme. |
48-
| 07 | [Part B — Trans-disciplinary Reasoning](sections/07-part-b-trans-disciplinary-reasoning-cluster/_index.md) | 24 | Compose subsystem properties, trust scores, cross-scale aggregation (Gamma algebra). |
49-
| 08 | [Part C — Kernel Extensions](sections/08-part-c-kernel-extensions-specifications/_index.md) | 30 | Characterize, compose, compare knowledge artifacts. Epistemic scoring (Formality, ClaimScope, Reliability). |
50-
| 09 | [Part D — Ethics & Conflict](sections/09-part-d-multi-scale-ethics-conflict-optimisation/_index.md) | 1 | Ethical trade-offs, conflict resolution, bias auditing, safety-evidence overriding utility. |
51-
| 10 | [Part E — Constitution & Authoring](sections/10-part-e---fpf-constitution-and-authoring-cluster/_index.md) | 0 | Entry point for Part E subsections. |
52-
| 11 | [E-I — FPF Constitution](sections/11-section-e-i---the-fpf-constitution/_index.md) | 29 | FPF vision/mission, the 11 Pillars, guard-rails, Multi-View Publication Kit (MVPK). |
53-
| 12 | [Part F — Unification Suite](sections/12-part-f-the-unification-suite-concept-sets-sensecells-contextual-role-a/_index.md) | 0 | Entry point for Part F subsections. |
54-
| 13 | [F.I — Context of Meaning](sections/13-cluster-f-i-context-of-meaning-raw-material/_index.md) | 19 | Semantic drift, homonym collisions, cross-domain vocabulary alignment, Alignment Bridges. |
55-
| 14 | [UTS Layout A](sections/14-block-fpf-u-type-unified-tech-name-unified-plain-name-plain-twin-gover/_index.md) | 0 | Cross-context unification table mapping concepts across standards (BPMN, PROV-O, ITIL). |
56-
| 15 | [UTS Layout B](sections/15-block-base-concept-scale-map/_index.md) | 1 | Discipline-oriented concept unification table (operations, physics, math). |
57-
| 16 | [Part G — SoTA Patterns Kit](sections/16-part-g-discipline-sota-patterns-kit/_index.md) | 15 | Discipline-specific patterns, SoTA Packs, TraditionCards, OperatorCards, selector-ready portfolios. |
58-
| 17 | [Part H — Glossary](sections/17-part-h-glossary-definitional-pattern-index/_index.md) | 0 | Canonical definitions, four-register naming, cross-references for FPF terms. |
59-
| 18 | [Part I — Annexes](sections/18-part-i-annexes-extended-tutorials/_index.md) | 0 | Deprecated aliases, walkthroughs, change log, external standards mappings. |
89+
| 02 | [Table of Content](sections/02-table-of-content/_index.md) | 0 | Navigate the spec, locate a pattern, trace inter-section dependencies. |
90+
| 03 | [Preface](sections/03-preface/_index.md) | 17 | **Onboard**: reading paths by role, FPF philosophy, purpose and non-goals. |
91+
| 04 | [Part A — Kernel](sections/04-part-a-kernel-architecture-cluster/_index.md) | 19 | **Decompose and assign**: holons, bounded contexts, roles, transformers, method/work separation. |
92+
| 05 | [A.IV.A — Signatures](sections/05-cluster-a-iv-a---signature-stack-boundary-discipline/_index.md) | 18 | **Set boundaries**: classify statements as definitions, gates, duties, or evidence. |
93+
| 06 | [A.V — Principles](sections/06-cluster-a-v---constitutional-principles-of-the-kernel/_index.md) | 29 | **Prevent confusion**: category errors, measuring, comparing, evidence graphs. |
94+
| 07 | [Part B — Reasoning](sections/07-part-b-trans-disciplinary-reasoning-cluster/_index.md) | 24 | **Compose and evaluate**: aggregation (Gamma), trust scores, emergence, reasoning cycles. |
95+
| 08 | [Part C — Extensions](sections/08-part-c-kernel-extensions-specifications/_index.md) | 30 | **Score and search**: epistemic quality (F-G-R), kinds, measurement, open-ended search. |
96+
| 09 | [Part D — Ethics](sections/09-part-d-multi-scale-ethics-conflict-optimisation/_index.md) | 1 | **Resolve conflicts**: ethical trade-offs, bias auditing, safety overrides. |
97+
| 10 | [Part E — Constitution](sections/10-part-e---fpf-constitution-and-authoring-cluster/_index.md) | 0 | Entry point for Part E subsections. |
98+
| 11 | [E-I — Constitution](sections/11-section-e-i---the-fpf-constitution/_index.md) | 29 | **Govern and publish**: 11 Pillars, guard-rails, multi-view publication (MVPK). |
99+
| 12 | [Part F — Unification](sections/12-part-f-the-unification-suite-concept-sets-sensecells-contextual-role-a/_index.md) | 0 | Entry point for Part F subsections. |
100+
| 13 | [F.I — Meaning](sections/13-cluster-f-i-context-of-meaning-raw-material/_index.md) | 19 | **Align vocabulary**: semantic drift, homonym collisions, Alignment Bridges. |
101+
| 14 | [UTS Layout A](sections/14-block-fpf-u-type-unified-tech-name-unified-plain-name-plain-twin-gover/_index.md) | 0 | **Map concepts** across standards (BPMN, PROV-O, ITIL). |
102+
| 15 | [UTS Layout B](sections/15-block-base-concept-scale-map/_index.md) | 1 | **Map concepts** across disciplines (operations, physics, math). |
103+
| 16 | [Part G — SoTA Kit](sections/16-part-g-discipline-sota-patterns-kit/_index.md) | 15 | **Harvest disciplines**: SoTA Packs, TraditionCards, OperatorCards, benchmarks. |
104+
| 17 | [Part H — Glossary](sections/17-part-h-glossary-definitional-pattern-index/_index.md) | 0 | **Look up terms**: canonical definitions, four-register naming, cross-references. |
105+
| 18 | [Part I — Annexes](sections/18-part-i-annexes-extended-tutorials/_index.md) | 0 | Walkthroughs, change log, external standards mappings. |
60106
| 19 | [Part J — Indexes](sections/19-part-j-indexes-navigation-aids/_index.md) | 0 | Concept-to-pattern, pattern-to-example, principle-trace indexes. |
61-
| 20 | [Part K — Lexical Debt](sections/20-part-k-lexical-debt/_index.md) | 2 | Mandatory terminology replacements and migration debt for deprecated terms. |
107+
| 20 | [Part K — Lexical Debt](sections/20-part-k-lexical-debt/_index.md) | 2 | **Fix terminology**: mandatory replacements and migration debt. |

0 commit comments

Comments
 (0)