diff options
| -rw-r--r-- | README.md | 1 | ||||
| -rw-r--r-- | assemble-pro-review-package/SKILL.md | 141 | ||||
| -rw-r--r-- | assemble-pro-review-package/agents/openai.yaml | 4 | ||||
| -rwxr-xr-x | assemble-pro-review-package/scripts/inline_section.py | 240 |
4 files changed, 386 insertions, 0 deletions
@@ -4,6 +4,7 @@ Standalone Codex skills that do not belong inside a specific parent project. Current skills: +- `assemble-pro-review-package`: throwaway reviewer handoff bundles centered on a single concatenated giga-prompt with aggressively inlined code, logs, and other textual context - `fahrenheit-451`: zero-based documentation purge and consolidation for markdown and plaintext notes - `haussmann`: zero-based Rust source-tree audit and reorganization for layout, module topology, and shared support placement - `redline`: logic-preserving wallclock optimization for a locked basket of invocations with measurement-first discipline diff --git a/assemble-pro-review-package/SKILL.md b/assemble-pro-review-package/SKILL.md new file mode 100644 index 0000000..5f0780c --- /dev/null +++ b/assemble-pro-review-package/SKILL.md @@ -0,0 +1,141 @@ +--- +name: assemble-pro-review-package +description: Assemble a throwaway review bundle for an external expert or professional reviewer. Use when the user asks for a pro review package, reviewer handoff, expert audit bundle, or similar package that should include a single synthesized review prompt, the most relevant current design/spec/audit material for a specific goal, and aggressively inlined code, logs, and other text surfaces from the local repo plus any relevant rival or prior-art codebases. +--- + +# Assemble Pro Review Package + +You are creating a design or implementation review package for an out-of-band pro model +or other expert to review. This package should focus on the task or subproblem supplied +by the user in context. If you feel the problem is too vague for targeted review, push back +and help the user sharpen it. + +Create the package in a subdir of `/tmp` unless the user asks otherwise. Do not +commit it. Echo back the path you've used when done. + +The reviewer-facing markdown surface must be a single top-level concatenated document. +Assume the prompt text itself is the primary payload and that helper zips are secondary +spillover only. Write that document so its full text can be copied directly into a +one-shot pro-model prompt without further assembly. Use theory of mind: write for a +highly capable reviewer who has no hidden context beyond the prompt text and any uploaded +overflow artifacts. + +Default to a giga-prompt posture. OpenAI currently documents a 400k context window for +manually selected GPT-5.4 Thinking on the ChatGPT Pro tier, with 272k input tokens and +128k max output. Spending roughly 100k input tokens on a single review handoff is +acceptable when the material is load-bearing. Do not be shy about inlining large logs, +code paths, or external reference surfaces when they materially bear on the question. Do +not pad with junk either. + +Use `scripts/inline_section.py` to append labeled sections into the prompt doc while +enforcing a hard 100k-token ceiling counted with `o200k_base` by default. OpenAI publicly +documents `tiktoken` as the tokenizer family to use programmatically for OpenAI models, +but does not publicly document the exact ChatGPT-web tokenizer mapping for GPT-5.4 Pro, so +`o200k_base` is the operative approximation unless better evidence is available. + +## Workflow + +1. Infer the review target. + Determine the specific implementation goal, design question, or problem statement. + +2. Write one top-level review prompt document. + Include: + - broad objective + - current tactical objective + - current live benchmark, failure regime, or otherwise uncertainty + - the exact question the reviewer should focus on + + Address the pro model directly. The document should read as an instruction + and context handoff to the reviewer, not as notes about a bundle someone + else prepared. + +3. Smart-concatenate the most relevant docs into sections of that document. + Usually: + - current pseudocode or normative spec + - current design note + - current audit or experiment note + + Include only what directly bears on the review target. + Do not emit multiple markdown docs when one structured document will do. + The prompt doc should normally contain the actual textual payload rather than an index + pointing to helper artifacts. + +4. Curate the largest useful inlined source surface that still clears the budget. + Include: + - the core local implementation files + - when relevant, relevant external reference files that encode e.g. + comparable mechanism in a rival implementation, reference literature + materials, tightly-relevant logs or metrics, etc. + + Use the budget aggressively when the omitted context would otherwise force the reviewer + to infer too much. Inline real source, real logs, and real rival code rather than + summarizing them away. Reviewer performance still degrades on irrelevant sludge, so + never lazily dump the whole source tree or giant logs without hand-attesting their + relevance. The standard is not "smallest possible bundle"; it is "maximally clarifying + bundle under the hard token ceiling." + +5. Keep markdown singular, raw, and top-level. + The package should have exactly one primary markdown handoff document in the + package root. Any reviewer-facing markdown content should be merged into that + document as sections rather than emitted as separate files. + +6. Treat zips as overflow, not as the primary review surface. + Zip only when: + - the payload is binary + - the payload is enormous and only partly load-bearing + - inlining it would burst the hard budget + - the reviewer may still benefit from optional deep inspection + + Prefer inlining textual artifacts directly. Do not put `.md` files inside the zips. + +7. Build a clear throwaway package. + Prefer: + - one top-level raw review prompt doc + - top-level zip files + - optional subdirectories only for unzipped source or artifact staging + +8. Make the prompt doc self-sufficient. + It should read as one coherent handoff prompt, not as a bag of fragments. + Use explicit section headings and refer to uploaded helper zips by filename + only when needed. + Do not use phrases like `this package` or `the package` inside the prompt + document. Write as if speaking directly to the reviewer about the task, + context, questions, and attached artifacts. + +9. Put an explicit front-matter note near the top of the prompt. + The note should explain that: + - the reviewer is expected to consume a very large inlined prompt + - this is intentional rather than accidental + - the current GPT-5.4 ChatGPT reasoning tier has enough context for it + - the reviewer should prefer the inlined text over any helper zip unless the prompt + explicitly points to the zip for overflow detail + + Suggested wording: + `This prompt intentionally inlines a very large amount of primary material. That is + deliberate rather than accidental: current GPT-5.4 ChatGPT reasoning tiers perform + better when the relevant source, logs, and reference implementations are present in the + prompt itself instead of hidden behind attachments. OpenAI currently documents 400k + context for manually selected GPT-5.4 Thinking on the Pro tier (272k input + 128k max + output), so spending roughly 100k input tokens on a single high-stakes review handoff + is well within the intended operating range. Treat the inlined text as the primary + review surface; use any uploaded overflow artifacts only when this prompt points you to + them explicitly.` + +## Selection Rule + +Include a file only if it: +- defines intended behavior +- explains the active failure or design pressure +- implements the hot path in question +- implements the external mechanism or reference point being compared, when such a comparison is relevant +- records the measurement motivating the review + +Prefer inlining the relevant span rather than merely listing the file path. + +## Output + +Report only: +- package root +- main review prompt doc path +- zip paths +- a short note on what was included diff --git a/assemble-pro-review-package/agents/openai.yaml b/assemble-pro-review-package/agents/openai.yaml new file mode 100644 index 0000000..2b0c091 --- /dev/null +++ b/assemble-pro-review-package/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Assemble Pro Review Package" + short_description: "Build reviewer handoff bundles" + default_prompt: "Use $assemble-pro-review-package to assemble a throwaway reviewer handoff with one aggressively inlined giga-prompt as the primary payload." diff --git a/assemble-pro-review-package/scripts/inline_section.py b/assemble-pro-review-package/scripts/inline_section.py new file mode 100755 index 0000000..2a8f4f3 --- /dev/null +++ b/assemble-pro-review-package/scripts/inline_section.py @@ -0,0 +1,240 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = "==3.13.*" +# dependencies = ["tiktoken==0.12.0"] +# /// + +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + +import tiktoken + + +LANGUAGE_BY_SUFFIX = { + ".c": "c", + ".cc": "cpp", + ".conf": "text", + ".cpp": "cpp", + ".css": "css", + ".csv": "csv", + ".go": "go", + ".h": "c", + ".hpp": "cpp", + ".html": "html", + ".java": "java", + ".js": "javascript", + ".json": "json", + ".jsonl": "json", + ".kt": "kotlin", + ".log": "text", + ".lua": "lua", + ".md": "markdown", + ".patch": "diff", + ".proto": "proto", + ".py": "python", + ".rb": "ruby", + ".rs": "rust", + ".sh": "bash", + ".sql": "sql", + ".toml": "toml", + ".ts": "typescript", + ".tsx": "tsx", + ".txt": "text", + ".xml": "xml", + ".yaml": "yaml", + ".yml": "yaml", +} + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description=( + "Append a labeled markdown section containing a file or excerpt to a " + "target document, while enforcing a hard total token budget." + ) + ) + parser.add_argument("source", type=Path, help="Source file to inline.") + parser.add_argument("target", type=Path, help="Markdown file to append into.") + parser.add_argument( + "--label", + help="Section label. Defaults to the source path as provided.", + ) + parser.add_argument( + "--start", + type=int, + default=1, + help="One-indexed start line, inclusive. Defaults to 1.", + ) + parser.add_argument( + "--end", + type=int, + help="One-indexed end line, inclusive. Defaults to EOF.", + ) + parser.add_argument( + "--heading-level", + type=int, + default=2, + help="Markdown heading level for the section. Defaults to 2.", + ) + parser.add_argument( + "--encoding", + default="o200k_base", + help="Tiktoken encoding name used for the hard budget. Defaults to o200k_base.", + ) + parser.add_argument( + "--model", + help=( + "Optional model name for encoding lookup. If unavailable, the script falls " + "back to --encoding." + ), + ) + parser.add_argument( + "--max-tokens", + type=int, + default=100_000, + help="Hard maximum for the full target document after append. Defaults to 100000.", + ) + return parser.parse_args() + + +def fail(message: str) -> "NoReturn": + print(f"error: {message}", file=sys.stderr) + raise SystemExit(2) + + +def normalize_span(start: int, end: int | None, total_lines: int) -> tuple[int, int]: + if start < 1: + fail("--start must be at least 1") + resolved_end = total_lines if end is None else end + if resolved_end < start: + fail("--end must be greater than or equal to --start") + if start > total_lines: + fail( + f"--start {start} exceeds the source length of {total_lines} line" + f"{'' if total_lines == 1 else 's'}" + ) + if resolved_end > total_lines: + fail( + f"--end {resolved_end} exceeds the source length of {total_lines} line" + f"{'' if total_lines == 1 else 's'}" + ) + return start, resolved_end + + +def resolve_language(path: Path) -> str: + return LANGUAGE_BY_SUFFIX.get(path.suffix.lower(), "text") + + +def load_encoding(model: str | None, encoding_name: str) -> tuple[tiktoken.Encoding, str]: + if model is not None: + try: + encoding = tiktoken.encoding_for_model(model) + return encoding, f"model:{model}->{encoding.name}" + except KeyError: + pass + return tiktoken.get_encoding(encoding_name), f"encoding:{encoding_name}" + + +def choose_fence(body: str) -> str: + longest_run = 0 + current_run = 0 + for char in body: + if char == "`": + current_run += 1 + longest_run = max(longest_run, current_run) + else: + current_run = 0 + return "`" * max(3, longest_run + 1) + + +def render_section( + *, + label: str, + source_name: str, + start: int, + end: int, + body: str, + language: str, + heading_level: int, +) -> str: + if heading_level < 1: + fail("--heading-level must be at least 1") + heading = "#" * heading_level + lines_label = f"{start}" if start == end else f"{start}-{end}" + fence = choose_fence(body) + if body and not body.endswith("\n"): + body = f"{body}\n" + return ( + f"{heading} {label}\n\n" + f"Source: `{source_name}`\n" + f"Lines: `{lines_label}`\n\n" + f"{fence}{language}\n" + f"{body}" + f"{fence}\n" + ) + + +def main() -> None: + args = parse_args() + source = args.source + target = args.target + + if not source.is_file(): + fail(f"source file not found: {source}") + + source_text = source.read_text(encoding="utf-8", errors="replace") + source_lines = source_text.splitlines(keepends=True) + if not source_lines: + fail("source file is empty") + + start, end = normalize_span(args.start, args.end, len(source_lines)) + excerpt = "".join(source_lines[start - 1 : end]) + label = args.label or str(source) + section = render_section( + label=label, + source_name=str(source), + start=start, + end=end, + body=excerpt, + language=resolve_language(source), + heading_level=args.heading_level, + ) + + existing = "" + if target.exists(): + if target.is_dir(): + fail(f"target is a directory: {target}") + existing = target.read_text(encoding="utf-8", errors="replace") + + separator = "\n\n" if existing else "" + rendered = f"{existing}{separator}{section}" + + encoding, encoding_label = load_encoding(args.model, args.encoding) + total_tokens = len(encoding.encode(rendered)) + section_tokens = len(encoding.encode(section)) + existing_tokens = len(encoding.encode(existing)) + + if total_tokens > args.max_tokens: + fail( + "refusing append because the projected document would exceed the hard budget: " + f"{total_tokens} > {args.max_tokens} ({encoding_label}; existing={existing_tokens}; " + f"section={section_tokens})" + ) + + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(rendered, encoding="utf-8") + + print(f"appended: {label}") + print(f"source: {source}") + print(f"target: {target}") + print(f"lines: {start}-{end}") + print(f"encoding: {encoding_label}") + print(f"section_tokens: {section_tokens}") + print(f"total_tokens: {total_tokens}") + + +if __name__ == "__main__": + main() |