pharaoh-tailor-fill

pharaoh-tailor-fill

When to use

Invoke after pharaoh-tailor-detect has produced a detected-conventions JSON report. This skill converts that report into the four files that Pharaoh reads at runtime from .pharaoh/project/.

Do NOT invoke without a detect report — guessing conventions without observation is unreliable. Do NOT invoke if tailoring files already exist unless the user explicitly confirms overwrite (see Guardrail G2).

(a) Debt logged — this skill fills 4 files in one invocation. If Phase-3 validation shows pharaoh-tailor-review systematically flags one file type more than others, consider splitting into tailor-fill-id-conventions, tailor-fill-workflows, tailor-fill-catalog, and tailor-fill-checklist. Until that evidence exists, the combined skill is correct scope: all four files form one logical tailoring unit and are authored together or not at all.

---

Inputs

• detected_conventions (from pharaoh-tailor-detect): the JSON report emitted by that skill
• target_dir (from user): path to .pharaoh/project/ where the four files will be written
• standard (from user, optional): iso26262-8.6 (default) or aspice-4.0 or iso21434 — controls which checklist is generated for checklists/requirement.md
• overwrite_ok (from user, optional, default false): if true, existing tailoring files are replaced; if false, fail if any target file already exists

---

Outputs

Four files written under <target_dir>:

1. id-conventions.yaml
2. workflows.yaml
3. artefact-catalog.yaml
4. checklists/requirement.md

Emit a summary after writing:

Written:
  <target_dir>/id-conventions.yaml        (<N> prefix entries)
  <target_dir>/workflows.yaml             (<N> states, <N> transitions)
  <target_dir>/artefact-catalog.yaml      (<N> artefact types)
  <target_dir>/checklists/requirement.md  (<standard> axes)

Run `pharaoh-tailor-review` to validate the generated files before using them.

---

Process

Step 1: Validate detected_conventions

Confirm the JSON has the required top-level keys: prefixes, separator, artefact_types, lifecycle_states_observed.

If any required key is missing, FAIL:

FAIL: detected_conventions JSON is malformed — missing key(s): <list>.
Re-run pharaoh-tailor-detect and pass its output directly to this skill.
Expected shape: {"prefixes": {...}, "separator": "...", "artefact_types": {...},
                 "lifecycle_states_observed": [...]}

---

Step 2: Check for existing files

If overwrite_ok is false (default), check whether any of the four target files exist:

• <target_dir>/id-conventions.yaml
• <target_dir>/workflows.yaml
• <target_dir>/artefact-catalog.yaml
• <target_dir>/checklists/requirement.md

If any exist, FAIL:

FAIL: Tailoring files already exist at <target_dir>:
  <list of existing files>
To replace them, re-run with overwrite_ok: true.

Create <target_dir>/checklists/ if it does not exist.

---

Step 3: Write id-conventions.yaml

Use prefixes, separator, id_regex_candidate, and id_regex_exceptions from the detect report.

Format:

# id-conventions.yaml — generated by pharaoh-tailor-fill from pharaoh-tailor-detect output
# Review id_regex_exceptions manually before committing.

separator: "__"

id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$"

# Per-type overrides for IDs that do not match id_regex above.
# Empty if none detected.
id_regex_exceptions: {}

prefixes:
  gd_req: GD_REQ_
  wp:     WP_
  wf:     WF_
  tc:     TC_
  # ... one entry per detected prefix

Rules:

• separator: value from detect report; if null, write separator: null # WARNING: not detected
• id_regex: value from id_regex_candidate; if null, write placeholder with warning comment
• id_regex_exceptions: map from detect report id_regex_exceptions; empty map if none
• prefixes: one key per detected prefix from detected_conventions.prefixes. The value is the identifier-prefix string that gets prepended to the local-part to form an id (e.g. REQ_, FEAT_, BRAKE_CTRL_, or just tc if the project uses the directive name itself as the prefix). Take the value from the detect report's prefixes[<key>]; if the detect report reports the prefix as the directive name itself (e.g. tc__), use the directive name as the value. Do not author human descriptions in the value position — prefixes is consumed by pharaoh-id-allocate and must be a literal prefix token, not prose.

---

Step 4: Write workflows.yaml

Use lifecycle_states_observed from the detect report.

4a. States

List all observed states. Add a short description using common conventions:

State	Description
draft	Initial authoring state — not yet reviewed
valid	Review completed — approved for use
inspected	Independent inspection passed
open	Item identified — not yet analysed
closed	Resolution confirmed — no action outstanding
active	In progress
deprecated	Superseded — do not use for new work

For any state not in this table, write "<state> — description not inferred; update manually".

4b. Default transitions

If the project does not encode transitions explicitly (none are present in needs.json), apply these sensible defaults based on the observed state set:

• [draft, valid, inspected] → standard V-model review chain:

  • draft → valid: requires ["independent_review_complete"]
  • valid → inspected: requires ["inspection_record_present"]
  • inspected → draft: requires [] (regression path, no prerequisite)

• [open, closed] → simple open/close:

  • open → closed: requires ["resolution_confirmed"]
  • closed → open: requires [] (reopen path)

• Any other combination → emit transitions for each adjacent pair with empty requires: [] and add a # TODO: fill in transition prerequisites comment.

Format:

# workflows.yaml — generated by pharaoh-tailor-fill
# Validates against schemas/workflows.schema.json.
# Review default transitions before committing.

lifecycle_states:
  - draft
  - valid
  - inspected

transitions:
  - from: draft
    to:   valid
    requires: [independent_review_complete]
  - from: valid
    to:   inspected
    requires: [inspection_record_present]
  - from: inspected
    to:   draft
    requires: []

State descriptions live in code review notes or per-project docs, not in workflows.yaml — lifecycle_states is a flat list of state-name strings per the schema. The optional note: field is not part of the schema and must be dropped from emitted output.

---

Step 5: Write artefact-catalog.yaml

Use artefact_types from the detect report.

For each artefact type, emit a YAML block:

<prefix>:
  required_fields: [<fields from observed_fields_required, excluding id — always implicit>]
  optional_fields: [<fields from observed_fields_optional>]
  lifecycle: [<lifecycle_states_observed>]   # omit if prefix has no status field
  required_links: [<link options observed on every need of this type>]
  optional_links: [<link options observed on some but not all needs of this type>]
  required_metadata_fields: [<option keys observed non-empty on every need of this type>]
  required_roles: [<reviewer/approval options observed non-empty on every need of this type>]

Rules for the basic shape:

• Include id and status in required_fields always (structural).
• Copy remaining observed_fields_required field names (drop counts — counts are detect output, not catalog schema).
• Copy observed_fields_optional field names similarly.
• Include lifecycle key only for types that carry a status field.
• Add a YAML comment noting frequency for any field that was close to the 95% threshold (between 90–95%): # <field>: present in <N>% of corpus — considered required by threshold.

Rules for the four release-gate fields. These are read by pharaoh-link-completeness-check, pharaoh-output-validate, and pharaoh-review-completeness and aggregated by pharaoh-quality-gate. Empty arrays are valid and explicit; absent keys are flagged by pharaoh-tailor-review rule C6:

• required_links: every link option that appears non-empty on ≥95% of needs of this type (same threshold as required_fields).
• optional_links: link options that appear on ≥20% but <95% of needs.
• required_metadata_fields: option keys (excluding link options and the structural id) that appear non-empty on ≥95% of needs of this type. Always include status for any type with a lifecycle.
• required_roles: include reviewer if observed non-empty on ≥80% of needs of this type; include approved_by if observed non-empty on ≥80%. The fill path is more opinionated than the bootstrap path: detected presence in the corpus is the signal that the project treats the role as required, even if the threshold for required_fields (95%) was not met.

Always emit all four keys, even as empty arrays. Empty array means "the project's data shows no requirement for this type"; omitting the key means "we never decided" — and rule C6 flags the latter at review time.

Worked example for a comp_req type whose corpus shows satisfies on every need, verifies on 60%, priority non-empty on every need, reviewer on 90%, and approved_by on 30%:

comp_req:
  required_fields: [id, status, title, satisfies]
  optional_fields: [reviewer, approved_by, priority, verifies]
  lifecycle: [draft, reviewed, approved]
  required_links: [satisfies]
  optional_links: [verifies]
  required_metadata_fields: [status, priority]
  required_roles: [reviewer]

Format header:

# artefact-catalog.yaml — generated by pharaoh-tailor-fill from pharaoh-tailor-detect output
# Threshold: required = present in >= 95% of instances; optional = >= 20%.
# Release-gate fields (required_links, optional_links, required_metadata_fields,
# required_roles) read by pharaoh-link-completeness-check, pharaoh-output-validate,
# pharaoh-review-completeness; aggregated by pharaoh-quality-gate. Empty array means
# "explicit no requirement"; absent key is flagged by pharaoh-tailor-review C6.

---

Step 6: Write checklists/requirement.md

Use the standard specified in the standard input (default iso26262-8.6).

ISO 26262-8 §6 axes (default):

---
title: "Requirement Quality Checklist — ISO 26262-8 §6"
standard: iso26262-8.6
axes:
  individual:
    - atomicity
    - internal_consistency
    - verifiability
    - unambiguity_prose
    - comprehensibility
    - feasibility
    - schema
  set_level:
    - completeness
    - external_consistency
    - no_duplication
  chain_level:
    - maintainability
---

# Requirement Quality Checklist

This checklist is used by `pharaoh-req-review` and `pharaoh-req-set-review`.

## Individual-requirement axes

| Axis | Type | Scale | Rule |
|---|---|---|---|
| atomicity | binary | 0/1 | Body contains exactly one `shall`; no coordinating conjunction joins modal verbs within the shall clause |
| internal_consistency | binary | 0/1 | Body contains no self-contradictory statement |
| verifiability | binary | 0/1 | `:verification:` present, non-empty, and resolves to a real need-id |
| schema | binary | 0/1 | All `required_fields` from artefact-catalog present and non-empty |
| unambiguity_prose | ordinal | 0–3 | 3 = unambiguous and precise; 0 = multiple conflicting interpretations |
| comprehensibility | ordinal | 0–3 | 3 = fully self-contained; 0 = incomprehensible without external context |
| feasibility | ordinal | 0–3 | 3 = clearly feasible and well-constrained; 0 = obviously infeasible |

## Set-level axes (deferred to pharaoh-req-set-review)

| Axis | Type | Notes |
|---|---|---|
| completeness | set | All behaviours of the parent element are captured |
| external_consistency | set | No conflict with sibling requirements or parent element |
| no_duplication | set | No requirement duplicates another in the set |

## Chain-level axes

| Axis | Type | Notes |
|---|---|---|
| maintainability | chain | Requirement set survives pharaoh-req-regenerate fixed-point within 2 iterations |

ASPICE 4.0 (SWE.2):

Replace the axes table with ASPICE SWE.2 base practice indicators. Emit a note: # ASPICE 4.0 SWE.2 BP coverage — use pharaoh-standard-conformance for per-indicator scoring.

ISO 21434 (security):

Replace with TARA/security requirement axes. Emit a note referencing pharaoh-standard-conformance for per-indicator scoring.

---

Guardrails

G1 — Malformed detect report

detected_conventions missing required keys → FAIL (Step 1) with explicit key list.

G2 — Existing tailoring, no overwrite permission

Any of the four target files already exists and overwrite_ok is false → FAIL (Step 2) listing the conflicting files. Never silently overwrite existing tailoring.

G3 — Null separator in detect report

If separator: null, write workflows.yaml and artefact-catalog.yaml as usual but set id_regex: null in id-conventions.yaml with a warning comment. Do not block the other three files.

G4 — Unknown standard

If standard is not one of iso26262-8.6, aspice-4.0, iso21434, FAIL:

FAIL: unknown standard "<standard>".
Supported values: iso26262-8.6 (default), aspice-4.0, iso21434.

---

Advisory chain

After writing all four files:

Run `pharaoh-tailor-review` to validate the generated files before using them.

---

Worked example

User input:

• detected_conventions: the report from the pharaoh-tailor-detect worked example (Score project)
• target_dir: /work/eclipse-score/.pharaoh/project/
• standard: iso26262-8.6 (default)
• overwrite_ok: false

Step 1: All required keys present. Validation passes.

Step 2: No existing files at target path. Continue.

Step 3 — id-conventions.yaml written: 6 prefix entries (gd_req, gd_chklst, std_req, tc, wf, wp); id_regex_exceptions includes std_req exception.

Step 4 — workflows.yaml written: States draft, inspected, valid with standard V-model default transitions: draft → valid (requires independent_review_complete), valid → inspected (requires inspection_record_present), inspected → draft (no prerequisite).

Step 5 — artefact-catalog.yaml written: 6 type entries. gd_req: required [id, status, satisfies], optional [complies, rationale, tags, verification]; complies gets a comment noting it was 93.5% (just below the 95% threshold — borderline, kept as optional).

Step 6 — checklists/requirement.md written: ISO 26262-8 §6 axes: 4 binary individual, 3 ordinal individual, 3 set-deferred, 1 chain.

Summary output:

Written:
  /work/eclipse-score/.pharaoh/project/id-conventions.yaml        (6 prefix entries)
  /work/eclipse-score/.pharaoh/project/workflows.yaml             (3 states, 3 transitions)
  /work/eclipse-score/.pharaoh/project/artefact-catalog.yaml      (6 artefact types)
  /work/eclipse-score/.pharaoh/project/checklists/requirement.md  (iso26262-8.6 axes)

Run `pharaoh-tailor-review` to validate the generated files before using them.