backspec 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. backspec/__init__.py +16 -0
  2. backspec/host/__init__.py +0 -0
  3. backspec/host/adapters/__init__.py +0 -0
  4. backspec/host/adapters/cache.py +103 -0
  5. backspec/host/adapters/cache_admin.py +64 -0
  6. backspec/host/adapters/capabilities_file.py +39 -0
  7. backspec/host/adapters/claude_code.py +77 -0
  8. backspec/host/adapters/codex.py +67 -0
  9. backspec/host/adapters/fake.py +39 -0
  10. backspec/host/adapters/filesystem.py +50 -0
  11. backspec/host/adapters/review_yaml.py +33 -0
  12. backspec/host/adapters/treesitter.py +130 -0
  13. backspec/host/cli.py +313 -0
  14. backspec/host/composition.py +211 -0
  15. backspec/kernel/__init__.py +0 -0
  16. backspec/kernel/llm.py +64 -0
  17. backspec/kernel/prompts.py +10 -0
  18. backspec/kernel/templates.py +12 -0
  19. backspec/kernel/text.py +23 -0
  20. backspec/kernel/usage.py +50 -0
  21. backspec/modules/__init__.py +0 -0
  22. backspec/modules/capabilities/__init__.py +0 -0
  23. backspec/modules/capabilities/domain.py +108 -0
  24. backspec/modules/capabilities/facade.py +48 -0
  25. backspec/modules/capabilities/ports.py +21 -0
  26. backspec/modules/capabilities/use_cases.py +63 -0
  27. backspec/modules/discovery/__init__.py +0 -0
  28. backspec/modules/discovery/domain.py +87 -0
  29. backspec/modules/discovery/facade.py +16 -0
  30. backspec/modules/discovery/ports.py +14 -0
  31. backspec/modules/discovery/use_cases.py +19 -0
  32. backspec/modules/evidence/__init__.py +0 -0
  33. backspec/modules/evidence/domain.py +276 -0
  34. backspec/modules/evidence/facade.py +24 -0
  35. backspec/modules/evidence/ports.py +12 -0
  36. backspec/modules/evidence/use_cases.py +128 -0
  37. backspec/modules/extraction/__init__.py +0 -0
  38. backspec/modules/extraction/facade.py +6 -0
  39. backspec/modules/extraction/use_cases.py +228 -0
  40. backspec/modules/lint/__init__.py +0 -0
  41. backspec/modules/lint/domain.py +152 -0
  42. backspec/modules/lint/facade.py +7 -0
  43. backspec/modules/lint/use_cases.py +16 -0
  44. backspec/modules/report/__init__.py +0 -0
  45. backspec/modules/report/domain.py +128 -0
  46. backspec/modules/report/dto.py +92 -0
  47. backspec/modules/report/facade.py +11 -0
  48. backspec/modules/report/renderers.py +220 -0
  49. backspec/modules/report/use_cases.py +127 -0
  50. backspec/modules/requirements/__init__.py +0 -0
  51. backspec/modules/requirements/domain.py +272 -0
  52. backspec/modules/requirements/facade.py +26 -0
  53. backspec/modules/requirements/use_cases.py +135 -0
  54. backspec/modules/review/__init__.py +0 -0
  55. backspec/modules/review/domain.py +129 -0
  56. backspec/modules/review/facade.py +32 -0
  57. backspec/modules/review/ports.py +15 -0
  58. backspec/modules/review/use_cases.py +89 -0
  59. backspec/modules/staleness/__init__.py +0 -0
  60. backspec/modules/staleness/domain.py +75 -0
  61. backspec/modules/staleness/facade.py +17 -0
  62. backspec/modules/staleness/ports.py +7 -0
  63. backspec/modules/staleness/use_cases.py +39 -0
  64. backspec/modules/triage/__init__.py +0 -0
  65. backspec/modules/triage/domain.py +144 -0
  66. backspec/modules/triage/facade.py +24 -0
  67. backspec/modules/triage/use_cases.py +79 -0
  68. backspec/prompts/assess.md +32 -0
  69. backspec/prompts/assign.md +18 -0
  70. backspec/prompts/consolidate.md +52 -0
  71. backspec/prompts/observe.md +52 -0
  72. backspec/prompts/orient.md +33 -0
  73. backspec/prompts/synthesise.md +97 -0
  74. backspec/prompts/triage.md +34 -0
  75. backspec/py.typed +0 -0
  76. backspec/templates/libre-baskerville-400.woff2 +0 -0
  77. backspec/templates/libre-baskerville-700.woff2 +0 -0
  78. backspec/templates/libre-baskerville-OFL.txt +93 -0
  79. backspec/templates/report.html +336 -0
  80. backspec-0.0.1.dist-info/METADATA +430 -0
  81. backspec-0.0.1.dist-info/RECORD +85 -0
  82. backspec-0.0.1.dist-info/WHEEL +4 -0
  83. backspec-0.0.1.dist-info/entry_points.txt +2 -0
  84. backspec-0.0.1.dist-info/licenses/LICENSE +21 -0
  85. backspec-0.0.1.dist-info/licenses/src/backspec/templates/libre-baskerville-OFL.txt +93 -0
@@ -0,0 +1,144 @@
1
+ """Triage: a cheap first look at each file, deciding which are worth reading in full.
2
+
3
+ The rule is here, not in the prompt. A file is skipped only when the model says its relevance is
4
+ `none` and says it is sure. Everything else is read: low relevance, unsure, a file the reply did
5
+ not mention, a batch whose call failed. Triage is conservative by construction.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import math
11
+ from dataclasses import dataclass
12
+
13
+ from pydantic import BaseModel, Field
14
+
15
+ from backspec.kernel.text import numbered
16
+
17
+ ROLES = ("ui", "api", "domain", "test", "docs", "infra", "config", "generated", "data", "other")
18
+ RELEVANCE = ("high", "medium", "low", "none")
19
+
20
+ PREVIEW_LINES = 40 # lines of each file the model sees
21
+ BATCH_FILES = 60 # files per call ...
22
+ BATCH_PREVIEW_LINES = 2500 # ... or preview lines per call, whichever comes first
23
+
24
+ AUDIT_MIN = 5
25
+ AUDIT_MAX = 50
26
+ DEFAULT_AUDIT = 0.1
27
+
28
+
29
+ class RawVerdict(BaseModel):
30
+ """One file's verdict as the model gave it. Anything missing counts against skipping."""
31
+ path: str
32
+ role: str = "other"
33
+ relevance: str = ""
34
+ sure: bool = False
35
+
36
+
37
+ class TriageReply(BaseModel):
38
+ files: list[RawVerdict] = Field(default_factory=list)
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class Verdict:
43
+ role: str
44
+ relevance: str
45
+ skipped: bool
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class EarlierVerdict:
50
+ """What an earlier run decided about one file, as the file was then."""
51
+ source_hash: str
52
+ verdict: Verdict
53
+
54
+
55
+ def is_skipped(relevance: str, sure: bool) -> bool:
56
+ """The whole rule: skip only a file that is surely of no relevance."""
57
+ return relevance == "none" and sure is True
58
+
59
+
60
+ def decide(raw: RawVerdict) -> Verdict:
61
+ role = raw.role.strip().lower()
62
+ relevance = raw.relevance.strip().lower()
63
+ return Verdict(role=role if role in ROLES else "other",
64
+ relevance=relevance if relevance in RELEVANCE else "unknown",
65
+ skipped=is_skipped(relevance, raw.sure))
66
+
67
+
68
+ def merge_duplicate(first: Verdict, second: Verdict) -> Verdict:
69
+ """A path the model answered twice is skipped only if both answers skip it."""
70
+ return Verdict(role=first.role, relevance=first.relevance, skipped=first.skipped and second.skipped)
71
+
72
+
73
+ def preview(path: str, lines: list[str]) -> str:
74
+ shown = lines[:PREVIEW_LINES]
75
+ cut = f", first {len(shown)} shown" if len(shown) < len(lines) else ""
76
+ header = f"=== FILE: {path} ({len(lines)} lines{cut}) ==="
77
+ return "\n".join([header, *numbered(shown, 1), ""])
78
+
79
+
80
+ def pack(sizes: list[tuple[str, int]]) -> list[list[str]]:
81
+ """Paths grouped into batches of at most BATCH_FILES files and BATCH_PREVIEW_LINES preview
82
+ lines, in order. `sizes` is (path, number of lines in the file)."""
83
+ batches: list[list[str]] = []
84
+ current: list[str] = []
85
+ used = 0
86
+ for path, size in sizes:
87
+ shown = min(size, PREVIEW_LINES)
88
+ if current and (len(current) >= BATCH_FILES or used + shown > BATCH_PREVIEW_LINES):
89
+ batches.append(current)
90
+ current, used = [], 0
91
+ current.append(path)
92
+ used += shown
93
+ if current:
94
+ batches.append(current)
95
+ return batches
96
+
97
+
98
+ def audit_size(skipped: int, fraction: float) -> int:
99
+ """How many skipped files the audit reads. 0 turns it off, 1.0 or more reads them all;
100
+ otherwise a fraction, at least AUDIT_MIN and at most AUDIT_MAX, or all if fewer than AUDIT_MIN."""
101
+ if skipped == 0 or fraction <= 0:
102
+ return 0
103
+ if fraction >= 1 or skipped < AUDIT_MIN:
104
+ return skipped
105
+ return min(skipped, max(AUDIT_MIN, min(AUDIT_MAX, math.ceil(skipped * fraction))))
106
+
107
+
108
+ def audit_sample(skipped: list[tuple[str, str]], fraction: float) -> list[str]:
109
+ """The paths of the skipped files to read anyway. `skipped` is (path, source hash). Chosen
110
+ by sorting on the sha256 of the source hash, so the same files are chosen every run."""
111
+ ranked = sorted(skipped, key=lambda s: (hashlib.sha256(s[1].encode()).hexdigest(), s[0]))
112
+ return sorted(path for path, _ in ranked[:audit_size(len(skipped), fraction)])
113
+
114
+
115
+ def _binomial_cdf(k: int, n: int, p: float) -> float:
116
+ """P(X <= k) for X ~ Binomial(n, p)."""
117
+ return sum(math.comb(n, i) * p ** i * (1 - p) ** (n - i) for i in range(k + 1))
118
+
119
+
120
+ def _bisect(f, target: float) -> float:
121
+ """The p in [0, 1] where the decreasing function f(p) crosses target."""
122
+ low, high = 0.0, 1.0
123
+ for _ in range(80):
124
+ middle = (low + high) / 2
125
+ if f(middle) > target:
126
+ low = middle
127
+ else:
128
+ high = middle
129
+ return (low + high) / 2
130
+
131
+
132
+ def clopper_pearson(successes: int, trials: int, confidence: float = 0.95) -> tuple[float, float] | None:
133
+ """The exact binomial confidence interval for a rate, or None when there were no trials."""
134
+ if trials <= 0:
135
+ return None
136
+ if not 0 <= successes <= trials:
137
+ raise ValueError("successes must be between 0 and trials")
138
+ tail = (1 - confidence) / 2
139
+ lower = 0.0
140
+ if successes > 0:
141
+ # P(X >= k | p) rises with p; the lower bound is where it reaches `tail`
142
+ lower = _bisect(lambda p: -(1 - _binomial_cdf(successes - 1, trials, p)), -tail)
143
+ upper = 1.0 if successes == trials else _bisect(lambda p: _binomial_cdf(successes, trials, p), tail)
144
+ return lower, upper
@@ -0,0 +1,24 @@
1
+ """Triage, as the rest of backspec sees it."""
2
+ from __future__ import annotations
3
+
4
+ from backspec.kernel.llm import LLMPort
5
+ from backspec.modules.discovery.facade import SourceFile
6
+ from backspec.modules.triage.domain import DEFAULT_AUDIT, EarlierVerdict, Verdict, clopper_pearson
7
+ from backspec.modules.triage.use_cases import TriageResult, fingerprint, triage
8
+
9
+ __all__ = ["DEFAULT_AUDIT", "EarlierVerdict", "TriageFacade", "TriageResult", "Verdict", "clopper_pearson"]
10
+
11
+
12
+ class TriageFacade:
13
+ def __init__(self, llm: LLMPort, workers: int = 4):
14
+ self._llm = llm
15
+ self._workers = workers
16
+
17
+ def assess(self, files: list[SourceFile], earlier: dict[str, EarlierVerdict] | None = None,
18
+ audit: float = DEFAULT_AUDIT) -> TriageResult:
19
+ """A verdict for each file that could be judged, and which skipped files the audit reads anyway."""
20
+ return triage(files, self._llm, self._workers, earlier, audit)
21
+
22
+ def fingerprint(self) -> str:
23
+ """Identifies the way files are triaged; verdicts made another way are not reused."""
24
+ return fingerprint()
@@ -0,0 +1,79 @@
1
+ """Triage every file from a preview, in parallel batches, and plan the audit of what it skips."""
2
+ from __future__ import annotations
3
+
4
+ from concurrent.futures import ThreadPoolExecutor
5
+ from dataclasses import dataclass, field
6
+
7
+ from backspec.kernel import prompts
8
+ from backspec.kernel.llm import LLMError, LLMPort, LLMRequest, ask
9
+ from backspec.kernel.text import short_hash
10
+ from backspec.modules.discovery.facade import SourceFile
11
+ from backspec.modules.triage.domain import (BATCH_FILES, BATCH_PREVIEW_LINES, PREVIEW_LINES, EarlierVerdict, TriageReply,
12
+ Verdict, audit_sample, decide, merge_duplicate, pack, preview)
13
+
14
+
15
+ @dataclass
16
+ class TriageResult:
17
+ verdicts: dict[str, Verdict] = field(default_factory=dict)
18
+ unresolved: dict[str, str] = field(default_factory=dict) # path -> why it has no verdict, so it is read
19
+ audited: list[str] = field(default_factory=list) # skipped files that are read anyway
20
+ batches: int = 0
21
+ reused_files: int = 0 # unchanged since the earlier run: verdict kept, not put to the model again
22
+
23
+ @property
24
+ def skipped(self) -> list[str]:
25
+ return sorted(path for path, verdict in self.verdicts.items() if verdict.skipped)
26
+
27
+ def to_read(self, files: list[SourceFile]) -> list[SourceFile]:
28
+ """The files the observe stage reads: everything not skipped, plus the audit sample."""
29
+ left_out = set(self.skipped) - set(self.audited)
30
+ return [f for f in files if f.path not in left_out]
31
+
32
+
33
+ def fingerprint() -> str:
34
+ """Changes whenever the way files are triaged does. Verdicts made another way are not reused."""
35
+ return short_hash(prompts.load("triage"), BATCH_FILES, BATCH_PREVIEW_LINES, PREVIEW_LINES, "skip-only-sure-none")
36
+
37
+
38
+ def triage(files: list[SourceFile], llm: LLMPort, workers: int = 4, earlier: dict[str, EarlierVerdict] | None = None,
39
+ audit: float = 0.0) -> TriageResult:
40
+ result = TriageResult()
41
+ by_path = {f.path: f for f in files}
42
+ to_ask: list[SourceFile] = []
43
+ for f in files:
44
+ known = (earlier or {}).get(f.path)
45
+ if known is not None and known.source_hash == f.source_hash:
46
+ result.verdicts[f.path] = known.verdict
47
+ result.reused_files += 1
48
+ else:
49
+ to_ask.append(f)
50
+ batches = pack([(f.path, len(f.lines)) for f in to_ask])
51
+ result.batches = len(batches)
52
+ instructions = prompts.load("triage")
53
+
54
+ def run(batch: list[str]) -> TriageReply | LLMError:
55
+ body = "\n".join(preview(path, by_path[path].lines) for path in batch)
56
+ try:
57
+ return ask(llm, LLMRequest("triage", f"{instructions}\n\n# The batch\n\n{body}", "fast"), TriageReply)
58
+ except LLMError as error:
59
+ return error
60
+
61
+ with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
62
+ replies = list(pool.map(run, batches))
63
+ for batch, reply in zip(batches, replies):
64
+ if isinstance(reply, LLMError):
65
+ for path in batch:
66
+ result.unresolved[path] = f"triage call failed: {str(reply)[:300]}"
67
+ continue
68
+ shown = set(batch)
69
+ for raw in reply.files:
70
+ if raw.path not in shown:
71
+ continue
72
+ verdict = decide(raw)
73
+ old = result.verdicts.get(raw.path)
74
+ result.verdicts[raw.path] = merge_duplicate(old, verdict) if old else verdict
75
+ for path in batch:
76
+ if path not in result.verdicts:
77
+ result.unresolved[path] = "the triage reply did not mention this file"
78
+ result.audited = audit_sample([(path, by_path[path].source_hash) for path in result.skipped], audit)
79
+ return result
@@ -0,0 +1,32 @@
1
+ # Assess-support stage
2
+
3
+ You are checking requirements against the code they cite. You did not write them. Be strict.
4
+
5
+ The requirements come at the end of this message, one block each. A block starts with `##### REQ-id`, then the
6
+ STATEMENT (and CONDITIONS if any), then one or more pieces of evidence. Each piece of evidence
7
+ shows numbered code lines; the lines marked `>` are the cited ones and the others are
8
+ surrounding context.
9
+
10
+ For each requirement, judge the whole statement, including every condition, against all of its
11
+ evidence taken together:
12
+
13
+ - `direct`: the evidence shows the complete behaviour as stated. Every part of the statement
14
+ and every condition can be pointed to in the shown code.
15
+ - `partial`: the evidence shows the main behaviour, but some part of the statement or a
16
+ condition is not shown. Name the missing part.
17
+ - `insufficient`: the evidence is related but does not show the behaviour, or shows only that
18
+ something exists.
19
+ - `conflicting`: the shown code disagrees with the statement. Say how.
20
+
21
+ A statement that says more than the shown code shows is `partial`, not `direct`. Code that only
22
+ shows a function, field or type exists is `insufficient` for a claim about behaviour. A test
23
+ counts as evidence of behaviour.
24
+
25
+ Do not use outside knowledge of the product. Judge only from the shown lines.
26
+
27
+ Reply with a single JSON object, and nothing else, in this shape, with one entry per requirement:
28
+
29
+ ```json
30
+ {"verdicts": [{"id": "REQ-1a2b3c4d", "support": "partial",
31
+ "note": "one short sentence; for anything but direct, exactly what is not shown, with the line number you rely on"}]}
32
+ ```
@@ -0,0 +1,18 @@
1
+ # Assign stage
2
+
3
+ At the end of this message are the capabilities of one software product, then a list of
4
+ observations about it. Each observation line is `OBS-id | statement`; `## path` lines say which
5
+ source file the following observations came from.
6
+
7
+ Assign every observation to exactly one capability id from the list: the one whose behaviour
8
+ the observation is evidence for. Judge by what the statement says, not by the file it came
9
+ from. Use `plumbing` only for internal mechanics no user or operator would notice.
10
+
11
+ ## Output
12
+
13
+ Reply with a single JSON object, and nothing else, with one entry for every OBS id given and
14
+ no others. Copy the ids exactly.
15
+
16
+ ```json
17
+ {"assignments": {"OBS-1a2b3c4d": "capability_id", "OBS-5e6f7a8b": "capability_id"}}
18
+ ```
@@ -0,0 +1,52 @@
1
+ # Consolidate stage
2
+
3
+ You are given the requirements already written for one capability of a software product. Each
4
+ has an id, a statement, its conditions, and the ids of the observations it cites. Many of them
5
+ are too fine: the same behaviour written several times, or one behaviour cut into pieces.
6
+ Your job is to say which requirements are the same behaviour and should become one.
7
+
8
+ ## What to merge
9
+
10
+ Merge requirements that:
11
+
12
+ - state one rule or behaviour, and differ only in a message, a reason string, a status name,
13
+ an enum value, a field or a file;
14
+ - are one rule cut into its cases (one per status, one per reason, one per kind of input):
15
+ write the rule once and put the cases in its conditions;
16
+ - show the same behaviour from different places (the check, the screen, the report, the test).
17
+
18
+ Do not merge requirements that a reviewer would test separately, or that have different actors
19
+ or different outcomes. When in doubt, leave it out. A requirement you do not mention is kept
20
+ unchanged.
21
+
22
+ ## How to write a merged requirement
23
+
24
+ - `statement`: one complete statement of the rule, at the level of the product. Use only what
25
+ the merged statements say. Do not add reasons or outcomes they do not state.
26
+ - `conditions`: the conditions of the merged requirements, joined and without repeats. Keep
27
+ the cases that distinguish the rule's variants.
28
+ - `level`: `user`, `system` or `technical`, as for the requirements merged.
29
+ - `merge`: the ids of the requirements this one replaces, copied exactly. At least two. A
30
+ requirement id may appear in only one group. Do not invent ids.
31
+
32
+ You do not write citations or scenarios. The program takes the evidence and the scenarios of the
33
+ merged requirements.
34
+
35
+ ## Output
36
+
37
+ Reply with a single JSON object, and nothing else:
38
+
39
+ ```json
40
+ {
41
+ "groups": [
42
+ {
43
+ "statement": "The system ...",
44
+ "conditions": ["..."],
45
+ "level": "system",
46
+ "merge": ["REQ-1a2b3c", "REQ-4d5e6f"]
47
+ }
48
+ ]
49
+ }
50
+ ```
51
+
52
+ If nothing should be merged, reply `{"groups": []}`.
@@ -0,0 +1,52 @@
1
+ # Observe stage
2
+
3
+ You are given one batch of source files from a software product, at the end of this message. Every line starts with its
4
+ real line number, then `|`, then the line. Your job is to record what these files establish
5
+ about the product's behaviour. You are collecting evidence. You are not writing requirements.
6
+
7
+ ## What to record
8
+
9
+ Go through each file and write one observation for each distinct thing it establishes that a
10
+ user, operator or calling system could notice. Look in particular for:
11
+
12
+ - what an entry point accepts and does: a route, a command, a UI action
13
+ - a permission or access check
14
+ - a validation, a limit, a refusal, and the error given
15
+ - a state change: what is saved, changed or deleted
16
+ - a rule for deciding something: a status, a category, an ordering
17
+ - what a test shows the product doing in a concrete case
18
+ - what is displayed to the user and when
19
+
20
+ Skip pure plumbing: imports, logging, formatting helpers, type declarations with no rule in
21
+ them. If a file holds nothing worth recording, list it under `none` with a short reason.
22
+
23
+ ## Rules
24
+
25
+ 1. One observation is one fact. Split anything that joins several.
26
+ 2. State only what these lines show. Do not guess at behaviour in code you cannot see.
27
+ 3. `lines` is the first and last line number of the code the observation rests on. Copy the
28
+ numbers printed at the start of the lines. Never count lines yourself. Keep the range tight:
29
+ usually under 30 lines.
30
+ 4. `quote` is a short piece of text copied exactly, character for character, from one line
31
+ inside that range. Leave out the line number and the `|`. Pick a distinctive line, not a
32
+ blank or a lone bracket.
33
+ 5. `path` is the file path exactly as printed in the `=== FILE:` header above the lines.
34
+ 6. `kind` is one of: `entry_point`, `permission`, `validation`, `state_change`, `rule`,
35
+ `display`, `error_path`, `test_case`, `doc_claim`, `other`.
36
+ 7. Write each `statement` as one plain sentence about the product, for example "A rule whose
37
+ test fails is given the status Broken." Do not mention function or variable names unless
38
+ the user would see them.
39
+
40
+ ## Output
41
+
42
+ Reply with a single JSON object, and nothing else, in this shape:
43
+
44
+ ```json
45
+ {
46
+ "observations": [
47
+ {"path": "pkg/file.py", "lines": [120, 134], "quote": "if result.failed:", "kind": "rule",
48
+ "statement": "A rule whose test fails is given the status Broken."}
49
+ ],
50
+ "none": [{"path": "pkg/other.py", "reason": "type declarations only"}]
51
+ }
52
+ ```
@@ -0,0 +1,33 @@
1
+ # Orient stage
2
+
3
+ At the end of this message is a list of observations about one software product, grouped under
4
+ the source file each came from. Each line is `OBS-id | statement`.
5
+
6
+ Propose the product capabilities these observations belong to. A capability is a feature area
7
+ as a user of the product would name it, for example "Password reset" or "Invoice export". It is
8
+ not a file, a layer or a technology. One source file can feed several capabilities, and one
9
+ capability usually draws on several files: server code, front-end code and tests.
10
+
11
+ ## Rules
12
+
13
+ - Propose capabilities that together cover the observations. Let the number follow the amount of
14
+ evidence: about one capability for every 25 to 40 observations, never fewer than 2 and never
15
+ more than 18. A hundred observations is 3 or 4 capabilities, not 10.
16
+ - Make them distinct; no two should overlap heavily. If two would share most of their
17
+ observations, they are one capability.
18
+ - Size them evenly where you can. Avoid one giant capability and avoid tiny ones.
19
+ - Add exactly one capability with id `plumbing` for observations that describe internal
20
+ mechanics no user or operator would notice.
21
+ - Give each an `id` (lowercase letters and underscores), a `name` (2 to 5 words), a `summary`
22
+ (one sentence saying what the user can do or see), and `includes` (3 to 6 short phrases
23
+ naming the kinds of observation that belong there, so that observations can be assigned
24
+ consistently).
25
+
26
+ ## Output
27
+
28
+ Reply with a single JSON object, and nothing else, in this shape:
29
+
30
+ ```json
31
+ {"capabilities": [{"id": "password_reset", "name": "Password reset",
32
+ "summary": "The user can ...", "includes": ["...", "..."]}]}
33
+ ```
@@ -0,0 +1,97 @@
1
+ # Synthesise stage
2
+
3
+ You are given the verified observations for one capability of a software product. Each
4
+ observation is one fact that a single source file establishes, already checked against the
5
+ code. Your job is to turn them into requirements: complete behaviours of the product, as a
6
+ user or operator would state them.
7
+
8
+ The capability's name and summary come at the end of this message, followed by the
9
+ observations. Each observation is one block:
10
+
11
+ OBS-id | kind | path:first-last
12
+ statement
13
+ quote: a line copied from the code
14
+
15
+ ## What a requirement is
16
+
17
+ - One behaviour that could be tested on its own. Split anything that joins several.
18
+ - Stated at the level of the product, not the code: "The developer can ...", "The system ...",
19
+ "Grounded ...". No function, class or variable names.
20
+ - Complete: say who or what acts, what happens, and under which conditions. A behaviour that
21
+ matters is usually spread over several observations from several files: the server code, the
22
+ front end and the tests. Combine them into one requirement and list all of them as evidence.
23
+ - Many observations describe the same behaviour from different files. Merge them. Do not
24
+ write one requirement per observation.
25
+
26
+ ## Rules
27
+
28
+ 1. Use only what the observations say. Do not add reasons, guarantees or outcomes that no
29
+ observation states.
30
+ 2. Every requirement lists the ids of the observations it rests on, copied exactly. You cannot
31
+ cite anything else. An id you invent or alter makes the requirement invalid.
32
+ 3. Give each cited observation a role:
33
+ - `establishes`: it shows part of the behaviour itself: the check, the rule, the change,
34
+ what is displayed, or a test demonstrating it.
35
+ - `context`: it only shows that something exists, such as a route or a field.
36
+ 4. `conditions` lists what the behaviour depends on: a state, a limit, a setting. Leave it
37
+ empty when there is none.
38
+ 5. `level` is `user` when a person using the product can see or do it, `system` when it is a
39
+ rule the product enforces behind the scenes, `technical` for internal mechanics.
40
+ 6. If the observations suggest a behaviour but leave a gap you would have to guess at, do not
41
+ guess. Add a line to `open_questions`.
42
+ 7. Consolidate hard. Write the fewest requirements that still cover what the capability does.
43
+ One requirement is one rule with all its conditions, citing every observation that shows it.
44
+ This is too fine, and you must not do it:
45
+ - one requirement per message string, status message or reason string: write the rule that
46
+ produces them once, and list the cases in `conditions`;
47
+ - one requirement per enum value, status or option: that is one rule with several cases;
48
+ - one requirement per file that shows the same behaviour: the server, the front end, the
49
+ report and the test are one requirement with several pieces of evidence;
50
+ - a requirement that only restates another from its test, or only adds a detail of wording.
51
+ The right grain is what a product owner would list as "what this capability does". Before
52
+ you answer, read your list again and merge any two that a reviewer would test together.
53
+ It is fine to leave trivia unused. Aim for roughly one requirement for every five to ten
54
+ observations, usually between 5 and 20 in all, and never more than one for every three
55
+ observations.
56
+
57
+ ## Scenarios
58
+
59
+ A requirement may carry `scenarios`: concrete cases written as given / when / then. Add one
60
+ only where an observation shows that concrete case. That is usually an observation of kind
61
+ `test_case` (a test with a given input and an expected result), or a documented example.
62
+
63
+ - Each scenario has a `name`, `given` (the starting state), `when` (the action or input) and
64
+ `then` (the observable result). All four must be filled in, from what the observations say.
65
+ - Each scenario lists the ids of the observations that show it, copied exactly, in the same
66
+ way as a requirement. A scenario that cites no real observation is discarded, and so is one
67
+ with a part left empty.
68
+ - Never invent a scenario to fill the field, and never turn a rule into an example that no
69
+ observation shows. Most requirements will have no scenarios, and that is correct: leave
70
+ `scenarios` empty or leave it out.
71
+
72
+ ## Output
73
+
74
+ Reply with a single JSON object, and nothing else, in this shape:
75
+
76
+ ```json
77
+ {
78
+ "requirements": [
79
+ {
80
+ "statement": "The developer can ...",
81
+ "conditions": ["..."],
82
+ "level": "user",
83
+ "evidence": [{"observation": "OBS-1a2b3c", "role": "establishes"}],
84
+ "scenarios": [
85
+ {
86
+ "name": "A short name for the case",
87
+ "given": "...",
88
+ "when": "...",
89
+ "then": "...",
90
+ "evidence": [{"observation": "OBS-4d5e6f", "role": "establishes"}]
91
+ }
92
+ ]
93
+ }
94
+ ],
95
+ "open_questions": ["..."]
96
+ }
97
+ ```
@@ -0,0 +1,34 @@
1
+ # Triage stage
2
+
3
+ You are given a batch of files from a software product, at the end of this message. For each
4
+ file you see its path, its size in lines, and its first lines, each with its real line number.
5
+ You are not reading the files in full. This is a quick first look, to decide which files are
6
+ worth reading closely for behaviour that a user or operator would notice.
7
+
8
+ ## What to say about each file
9
+
10
+ - `role`: what the file is, one of `ui`, `api`, `domain`, `test`, `docs`, `infra`, `config`,
11
+ `generated`, `data`, `other`.
12
+ - `relevance`: how likely the file holds behaviour a user or operator would notice (screens,
13
+ routes, commands, permissions, validation, rules, state changes, what tests show the product
14
+ doing, claims in documentation). One of `high`, `medium`, `low`, `none`.
15
+ - `sure`: `true` only if the preview is enough for you to be confident of the relevance. If the
16
+ preview is cut off and the rest could hold something different, or the file is unusual, say
17
+ `false`.
18
+
19
+ ## Rules
20
+
21
+ 1. Answer for every file in the batch, with `path` exactly as printed in the `=== FILE:` header.
22
+ 2. Use `none` only for a file that plainly holds no behaviour: lock files, build and tool
23
+ configuration, generated code, fixtures and vendored or bulk data. When in doubt, use `low`
24
+ or `sure: false`. A file you are not sure about is read in full anyway; a file wrongly
25
+ dismissed is lost.
26
+ 3. Judge from what you see. Do not guess at what the rest of the file might hold.
27
+
28
+ ## Output
29
+
30
+ Reply with JSON only, in this shape:
31
+
32
+ ```json
33
+ {"files": [{"path": "src/app.py", "role": "api", "relevance": "high", "sure": true}]}
34
+ ```
backspec/py.typed ADDED
File without changes