@1aboveio/core-skills 0.1.10 → 0.1.11

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 (33) hide show
  1. package/README.md +2 -1
  2. package/package.json +3 -3
  3. package/skills/distill-writing/SKILL.md +3 -3
  4. package/skills/distill-writing/references/extraction.md +1 -1
  5. package/skills/doc-to-md/SKILL.md +1 -1
  6. package/skills/editorial-review/SKILL.md +82 -12
  7. package/skills/editorial-review/references/checklist.md +26 -1
  8. package/skills/house-style/SKILL.md +8 -3
  9. package/skills/house-style/references/analytical-reporting.md +123 -0
  10. package/skills/house-style/references/analytical-writing-patterns.md +79 -0
  11. package/skills/house-style/references/analytical-writing-research.md +129 -0
  12. package/skills/{write-doc → house-style}/references/bilingual.md +7 -5
  13. package/skills/house-style/references/definitions-and-metrics.md +86 -0
  14. package/skills/house-style/references/document-workflow.md +193 -0
  15. package/skills/house-style/references/initialization.md +66 -0
  16. package/skills/house-style/references/persistence.md +9 -4
  17. package/skills/house-style/references/rules.md +11 -4
  18. package/skills/house-style/scripts/init-guidance.mjs +213 -0
  19. package/skills/house-style/templates/analytical-report.md +54 -0
  20. package/skills/house-style/templates/gap-analysis.md +1 -1
  21. package/skills/plain-language/SKILL.md +2 -2
  22. package/skills/polish-cn/SKILL.md +9 -2
  23. package/skills/reg-parser/SKILL.md +3 -3
  24. package/skills/terminology/SKILL.md +8 -4
  25. package/skills/write-doc/SKILL.md +40 -151
  26. package/skills/write-report/LICENSE +3 -0
  27. package/skills/write-report/SKILL.md +129 -0
  28. package/skills/{write-doc → write-report}/references/compliance-reports.md +4 -4
  29. package/skills/write-report/release-check.mjs +95 -0
  30. /package/skills/{write-doc → write-report}/references/reports/audit-report-template.md +0 -0
  31. /package/skills/{write-doc → write-report}/references/reports/external-assessment-template.md +0 -0
  32. /package/skills/{write-doc → write-report}/references/reports/management-report-template.md +0 -0
  33. /package/skills/{write-doc → write-report}/references/reports/vars-report-template.md +0 -0
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: write-report
3
+ description: "Write or edit analytical reports from data, research, analysis or findings: payment, fraud, operational, performance, research, gap-analysis, audit, external assessment, management and Visa VARS reports. Use whenever asked to report results, write up findings, or turn analysis into a report, even without naming this skill. English, Chinese or bilingual; Markdown by default, export when requested. NOT for defining requirements, policies or proposals (write-doc), performing the underlying domain analysis or audit, chat-only answers (plain-language), or learning house style (distill-writing)."
4
+ release-version: 0.45.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Write an analytical report
8
+
9
+ **Every analytical section must make a supported point. Its evidence should establish that
10
+ point, and its limitations should explain what would change the reader's interpretation or action.**
11
+
12
+ Explain what was examined, what was found, how strongly the sources support it, and what the
13
+ reader should decide or do. Recommendations may follow findings; they do not turn a report
14
+ into a proposal or authorize changing the underlying analysis.
15
+
16
+ An explicit user `/write-report` invocation first follows
17
+ [local initialization](../house-style/references/initialization.md) to persist `WRITING.md`,
18
+ `TERMINOLOGY.md` and their loading pointers. Automatic selection or a domain call does not
19
+ initialize guidance. This skill coordinates drafting, `editorial-review`, fixes, optional
20
+ `polish-cn`, regeneration and checks. The caller supplies domain requirements, not separate
21
+ commands for each writing stage. Standard mode is the default; explicit fast mode uses one
22
+ local review pass while preserving factual, analytical and domain requirements.
23
+
24
+ Before drafting or substantive editing, read the
25
+ [analytical reporting rules](../house-style/references/analytical-reporting.md), including their
26
+ required [writing patterns](../house-style/references/analytical-writing-patterns.md) and
27
+ [definitions and metrics](../house-style/references/definitions-and-metrics.md). These apply
28
+ even when another skill calls only this report stage. Load them for delegated writers and
29
+ reviewers too; a skill name or installed dependency does not transfer instructions.
30
+
31
+ Read and follow the [shared drafting and editing workflow](../house-style/references/document-workflow.md)
32
+ in full for source discipline, gaps, terminology, review, narrow edits and delivery. Follow
33
+ [house-style rules](../house-style/references/rules.md) for lookup and precedence. Start guidance
34
+ lookup beside the primary input file; with pasted input, start beside the output, else in the
35
+ working directory. Do not merge client guides or edit WRITING.md just because you read it.
36
+ Use [defaults](../house-style/references/defaults.md) and the applicable
37
+ [English](../house-style/references/style-en.md) or [Chinese](../house-style/references/style-zh.md)
38
+ guide where local guidance is silent. For Chinese or bilingual output, follow
39
+ [bilingual mode](../house-style/references/bilingual.md).
40
+
41
+ ## Route and select
42
+
43
+ - Analytical reports of any subject stay here. Defining a requirement, policy, procedure,
44
+ or proposal belongs to `write-doc`. Reporting current-state gaps against an established
45
+ baseline stays here; defining new requirements belongs to `write-doc`.
46
+ A PRD for a reporting feature is not an analytical report. A short answer requested only
47
+ in chat does not require a saved report.
48
+ - Domain skills own the underlying work: payment metrics, fraud rules, contract review,
49
+ research methods and compliance assessment. If analysis is missing, use the appropriate
50
+ skill before writing its conclusions. Do not present a writing pass as a fresh audit,
51
+ rerun a domain pipeline unnecessarily, or fabricate results to fill a report.
52
+ - A domain skill may call this skill for its report stage. Keep its named template,
53
+ calculation definitions, validation requirements, charts, output format and artifacts.
54
+ Before drafting, note which outputs and checks that workflow requires, which are conditional,
55
+ and which are preferences, including any required Chinese polish. This skill completes the
56
+ writing stages and returns their checked version and open items. The domain workflow retains
57
+ remaining domain validation and delivery; it reuses completed writing passes rather than
58
+ repeating them. Its output requirements take precedence over this skill's Markdown default.
59
+ - For audit, external assessment, management assessment or VARS reports, read
60
+ [compliance reports](references/compliance-reports.md) before drafting or editing.
61
+ Board-facing analytical reports do not automatically need compliance checks; use the
62
+ assessment branch only when reporting a compliance assessment.
63
+ - Learning style or saving a future-report preference belongs to `distill-writing`.
64
+ For an explicit save during writing, follow its
65
+ [save procedure](../house-style/references/persistence.md), then resume. A one-off
66
+ correction stays local to this report.
67
+
68
+ Choose the user's or producing skill's explicit template first, then a matching project
69
+ template, then the relevant bundled layout (including
70
+ [gap-analysis](../house-style/templates/gap-analysis.md) for current state against a baseline).
71
+ Without one, use
72
+ [analytical-report](../house-style/templates/analytical-report.md). Mandated report structures
73
+ and wording remain protected; a style preference cannot override them.
74
+
75
+ ## Establish the analytical basis
76
+
77
+ Before outlining a new report, record the reader's question, scope, source files and versions,
78
+ period, population, units, methods and limitations. Read the relevant source material, not
79
+ just a summary when the conclusion needs underlying detail. Ask once only for missing inputs
80
+ that block the reader's decision; otherwise narrow the claim and disclose the limitation.
81
+
82
+ - Trace material claims to source locations. Separate observed facts, calculations,
83
+ interpretations, assumptions and proposed actions. A hypothesis is not an established cause.
84
+ - Reconcile totals and derived metrics. State the numerator, denominator, exclusions, time
85
+ basis and units for rates. Do not treat missing observations as zero or extrapolate a
86
+ selected extract to a whole population without support.
87
+ - Compare like with like. Identify changes in scope, period, sample, currency or method.
88
+ Do not claim improvement, deterioration or significance from incomparable or absent baselines.
89
+ - Preserve source findings, IDs, ratings and uncertainty. Describe disagreements between
90
+ sources rather than silently choosing the more convenient number or conclusion.
91
+ - Use charts and tables when they help answer the question. Their populations, units, labels
92
+ and source values must agree with the prose. Keep supplied visual artifacts and links usable;
93
+ do not invent measurements or decorative data.
94
+ - Recommend actions proportionate to the findings. Costs, targets, owners, dates and expected
95
+ benefits need sources or explicit proposal/gap labels. State what the evidence cannot establish.
96
+
97
+ ## Draft, review and deliver
98
+
99
+ Use the argument outline, definition checks and writing patterns from the required shared rules;
100
+ follow the shared workflow with the selected template. Keep this sequence visible in working
101
+ notes or the task checklist so loading instructions is not confused with executing a review:
102
+
103
+ 1. Draft and save the report and its required charts/tables from the established results.
104
+ 2. Reopen that saved version and run `editorial-review` with the selected template, sources,
105
+ review mode and applicable domain checks. Save its brief review result to an existing working
106
+ file or a scratch file: identify the version, reader answers and concrete source checks,
107
+ even with no findings. A reread followed by a clean-review claim does not complete this stage.
108
+ Record findings before fixing; apply fixes and recheck changed claims against the sources.
109
+ 3. For Chinese text, execute `polish-cn` only when selected by the user or required by local or
110
+ domain policy, after content and any bilingual equivalence are final. Installation alone does
111
+ not select polish. Fast mode skips only optional polish, not an explicit or required pass.
112
+ 4. Regenerate when applicable and inspect the final reader-facing outputs. Check required
113
+ artifacts, source links and domain checks, not just the prose. A table or a description of a
114
+ chart does not satisfy a chart requirement. Record missing work as incomplete.
115
+ 5. Return to the producing workflow when there is one; otherwise deliver as below. Keep review
116
+ notes outside the business report. Reuse the saved working review record rather than
117
+ creating another review artifact.
118
+
119
+ For a narrow edit, use the shared narrow-edit branch. Verify affected claims and linked totals;
120
+ do not demand the entire dataset for an unrelated spelling correction. Reassessment, new
121
+ substantive claims and finalization require the supporting sources and applicable full checks.
122
+
123
+ Save to the requested path or format, else the project's output location, else
124
+ `./analytical-report-<short-topic>.md`; compliance-specific filenames follow their reference.
125
+ For a requested DOCX or PDF, render and inspect that export as well. Check citations and asset
126
+ links from the final location. Do not copy confidential sources into a delivery bundle without
127
+ authorization. Report the path, guidance and template used, checks performed, unresolved material
128
+ gaps, proposed decisions and limits on the conclusions. Do not claim a missing analysis, review,
129
+ export or external approval was completed.
@@ -1,6 +1,6 @@
1
1
  # Compliance reports
2
2
 
3
- Use this reference within the `write-doc` workflow when audit findings become a report.
3
+ Use this reference within the `write-report` workflow when audit findings become a report.
4
4
  It replaces the retired `report-writing` skill. For a narrow edit to an existing report, use
5
5
  [the edit branch](#edit-an-existing-report) before the full-report steps below.
6
6
  Do not repeat the audit or silently change
@@ -29,7 +29,7 @@ that is not a report of an assessment.
29
29
  ## Edit an existing report
30
30
 
31
31
  A copy-edit that changes no finding, rating, scope, count, recommendation or mandated text
32
- follows `write-doc`'s narrow-edit workflow. Read the existing report and applicable guidance;
32
+ follows `write-report`'s narrow-edit workflow. Read the existing report and applicable guidance;
33
33
  verify only the passages and facts affected by the change. Do not require the complete tracker
34
34
  for an unrelated spelling or formatting correction, re-audit the report, or call the edit a
35
35
  new assessment or finalization. Preserve protected text and all unaffected content.
@@ -46,7 +46,7 @@ category, status (Pass / Fail / Partial / N/A), severity (Critical / Major / Min
46
46
  Observation), observations, evidence and recommendations. Normalize other input shapes
47
47
  without inventing missing values. Flag missing status or severity; never turn an unknown
48
48
  into Pass or a lower severity. Mark missing evidence as **Evidence Pending**, keeping
49
- the finding visible. Missing facts follow `write-doc`'s gap rules.
49
+ the finding visible. Missing facts follow `write-report`'s gap rules.
50
50
 
51
51
  Preserve original IDs. Assign `F-001`, `F-002`, and so on only when IDs are absent.
52
52
  Link findings to remediation and evidence by ID. Keep source ratings, scales, findings
@@ -85,7 +85,7 @@ without checking it.
85
85
 
86
86
  ## Draft and review
87
87
 
88
- Use `write-doc`'s outline, draft, editorial review, fix and delivery steps. Apply the
88
+ Use `write-report`'s outline, draft, editorial review, fix and delivery steps. Apply the
89
89
  nearest WRITING.md from the findings file's directory, or for pasted input the output
90
90
  directory, else the working directory, under the shared lookup rules. Never edit it.
91
91
  For non-VARS reports, follow the selected template's structure. House style must not change
@@ -0,0 +1,95 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from 'node:child_process';
3
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
+ import { homedir } from 'node:os';
5
+ import { dirname, join, resolve } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ const DAY_MS = 24 * 60 * 60 * 1000;
9
+ const WEEK_MS = 7 * DAY_MS;
10
+ const here = dirname(fileURLToPath(import.meta.url));
11
+
12
+ function readJson(path, fallback = {}) {
13
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
14
+ }
15
+
16
+ function frontmatterValue(text, key) {
17
+ const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
18
+ const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
19
+ return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
20
+ }
21
+
22
+ function repositoryOf(source) {
23
+ const value = String(source ?? '').trim();
24
+ const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
25
+ return match?.[1] ?? null;
26
+ }
27
+
28
+ function stableVersion(value) {
29
+ const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
30
+ return match ? match.slice(1).map(Number) : null;
31
+ }
32
+
33
+ function newer(left, right) {
34
+ for (let index = 0; index < 3; index += 1) {
35
+ if (left[index] !== right[index]) return left[index] > right[index];
36
+ }
37
+ return false;
38
+ }
39
+
40
+ function writeCache(path, value) {
41
+ try {
42
+ mkdirSync(dirname(path), { recursive: true });
43
+ writeFileSync(path, JSON.stringify(value));
44
+ } catch { /* A read-only cache must not block skill use. */ }
45
+ }
46
+
47
+ function main(now = Date.now()) {
48
+ if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
49
+ const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
50
+ if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
51
+ const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
52
+ const name = frontmatterValue(skill, 'name');
53
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
54
+ if (!name || !localVersion) return;
55
+
56
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
57
+ const entry = lock.skills?.[name];
58
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
59
+ if (!repository) return;
60
+
61
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
62
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
63
+ const all = readJson(cachePath);
64
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
65
+
66
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
67
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
68
+ encoding: 'utf8',
69
+ stdio: ['ignore', 'pipe', 'ignore'],
70
+ timeout: 1500,
71
+ });
72
+ cache.lastCheck = now;
73
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
74
+ else delete cache.latestTag;
75
+ all[repository] = cache;
76
+ writeCache(cachePath, all);
77
+ }
78
+
79
+ const latestVersion = stableVersion(cache.latestTag);
80
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
81
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
82
+
83
+ cache.notifiedTag = cache.latestTag;
84
+ cache.notifiedAt = now;
85
+ all[repository] = cache;
86
+ writeCache(cachePath, all);
87
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
88
+ process.stdout.write(
89
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
90
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
91
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
92
+ );
93
+ }
94
+
95
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }