update agent, skill and scripts
This commit is contained in:
KOKO\Mimi
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-formulation-spec
|
||||
description: Use when an approved structural FEM feature needs an implementation-ready mathematical formulation before numerical review or coding.
|
||||
description: Produce an implementation-ready mathematical formulation for a new or changed structural FEM model.
|
||||
---
|
||||
|
||||
# FEM Formulation Specification
|
||||
|
||||
Translate approved requirements and research into a complete mathematical contract, independent of programming APIs and storage formats.
|
||||
Define only the model required by the assigned feature: assumptions, strong/weak form, kinematics, constitutive update, discretization, DOF/component and sign conventions, residual, consistent tangent where applicable, integration, state update, recovery, and formulation-level invariants. Distinguish small/large deformation and analysis-family assumptions.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/<feature-id>/requirements.md`
|
||||
- `docs/<feature-id>/research.md`
|
||||
- Governing standards and approved analysis assumptions
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Fix primary variables, degrees of freedom, units, coordinates, signs, configuration, and boundary-condition conventions.
|
||||
2. Derive governing strong and weak forms with all natural and essential boundary terms.
|
||||
3. Define discretization, interpolation, kinematics, constitutive update contract, element residual/internal and external forces, and consistent tangent or stiffness.
|
||||
4. Define mapping, Jacobian validity, quadrature, state/history evolution, constraints, and result recovery that apply to the selected analysis family.
|
||||
5. State dimensions, invariants, algorithm pseudocode, numerical risks, and tests capable of falsifying each derivation.
|
||||
|
||||
Read [analysis-family guidance](references/analysis-families.md) and apply only the sections selected by the requirements. Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for unresolved physics choices and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for return data.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/formulation.md` with assumptions; variables; strong/weak forms; discretization; kinematics; constitutive contract; element equations; integration; algorithms; recovery; numerical risks; verification implications; and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Every equation defines symbols, dimensions, configuration, sign, coordinate basis, and source or derivation. Show linearization when a consistent tangent is required. Link risks and checks to requirement IDs.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not design source-level APIs, parsers, storage schemas, or implementation tasks. Do not silently choose physics, stabilization, interpolation, constitutive behavior, or solver semantics outside the approved contract; return that critical choice for decision.
|
||||
Use approved requirements and evidence; consult [analysis-family guidance](references/analysis-families.md) when specifying that family's formulation. Make physics-changing choices explicit and return unresolved scope or evidence gaps rather than silently choosing them. Include verification implications, but do not prescribe C++ storage, persistent schema, tolerance values, or reference-result edits.
|
||||
|
||||
@@ -1,50 +1,12 @@
|
||||
---
|
||||
name: fem-implementation-tdd
|
||||
description: Use when planning, implementing, correcting, building, testing, or reference-comparing structural FEM solver code under approved upstream contracts.
|
||||
description: Plan, implement, or correct structural FEM solver code with behavior-focused tests and configured verification.
|
||||
---
|
||||
|
||||
# FEM Implementation TDD
|
||||
# FEM Implementation
|
||||
|
||||
Implement only approved structural-solver behavior and produce reproducible RED/GREEN/verification evidence.
|
||||
Read the assigned task, directly affected contracts, and repository build configuration. Keep the change minimal and preserve public boundaries, units, ordering, state ownership, deterministic behavior, and fail-closed diagnostics.
|
||||
|
||||
## Inputs
|
||||
For changed behavior, add or update meaningful verification and observe the failure before a bug fix when practical. Then implement the smallest correction and run affected configured checks. Run the configured full build/test once when the solver feature is complete, requested, or needed after broad impact. Required reference comparison must validate identity, quantities, units, row completeness, finite values, metrics, and the approved tolerance; do not alter references or tolerances to pass.
|
||||
|
||||
- Project instructions, architecture decisions, and Harness configuration
|
||||
- Approved requirements, formulation, numerical review, reference model, and I/O contract
|
||||
- Implementation plan and Executor-selected current step when Harness is active
|
||||
- Existing implementation and validation reports when correcting a failure
|
||||
|
||||
## Workflow
|
||||
|
||||
1. For planning, map every requirement to bounded tasks, tests, commands, dependencies, and owned files. Leave critical upstream choices unresolved and return them to their owner.
|
||||
2. For execution, change only the selected step. Write one focused test, run it, and observe the expected failure before production code.
|
||||
3. Implement the minimum change; run the focused test, configured build/test suite, and declared comparison gates.
|
||||
4. Classify failures as `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, or `upstream-contract`. Fix implementation-owned failures; route the rest.
|
||||
5. Update only artifacts and status fields owned by the current role. The Executor owns step selection, transport/session retry, timestamps, commits, and phase advancement. The Coordinator owns normalized `retry_key` state, correction attempts, and the workflow retry budget.
|
||||
|
||||
Read [toolchain and verification](references/toolchain-and-verification.md) before choosing commands. Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for reports and [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for escalation.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Produce the applicable canonical artifacts:
|
||||
|
||||
- `docs/<feature-id>/implementation-plan.md`
|
||||
- `docs/<feature-id>/implementation-report.md`
|
||||
- `docs/<feature-id>/build-test.md`
|
||||
- `docs/<feature-id>/reference-comparison.md`
|
||||
- `docs/<feature-id>/corrections.md`
|
||||
|
||||
Each task and test traces to requirement IDs and owned files. Create only artifacts applicable to the dispatched role and completed gate.
|
||||
|
||||
## Evidence
|
||||
|
||||
Record the RED failure reason, GREEN result, exact commands, exit codes, duration, relevant output, environment/config selection, changed artifacts and hashes, comparison prechecks and tolerance source, failure classification, assumptions, and residual risk.
|
||||
|
||||
## Boundary
|
||||
|
||||
Never write production behavior before observing the corresponding test fail. Hooks are guardrails, not RED evidence. Do not change requirements, formulations, I/O contracts, tolerances, or reference artifacts to make tests pass. Do not run licensed external solvers, publish, deploy, or perform destructive version-control operations without explicit authorization.
|
||||
|
||||
If the same retry key fails after the coordinator's bounded correction cycle, return the failure; do not loop or broaden scope.
|
||||
Read [toolchain-and-verification.md](references/toolchain-and-verification.md) when selecting configured commands or evaluating comparison evidence. Return changed files, commands and exit codes, decisive results, and blockers. Do not require phase files, automatic Git actions, or a formal RED/GREEN report for harmless refactors with sufficient coverage.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "FEM Implementation TDD"
|
||||
short_description: "Implement and verify structural FEM code"
|
||||
default_prompt: "Use $fem-implementation-tdd to plan or implement an approved structural FEM solver change test-first."
|
||||
default_prompt: "Use $fem-implementation-tdd to implement and verify this structural FEM solver change."
|
||||
|
||||
@@ -1,34 +1,7 @@
|
||||
# Toolchain and Verification
|
||||
|
||||
## Command authority
|
||||
Choose actual commands from `.harness/config.json`, then project presets/build metadata and repository instructions. `python scripts/execute.py` runs the configured complete build/test; use actual configured commands directly for focused checks. Missing metadata is not a passing solver validation.
|
||||
|
||||
Choose commands in this order:
|
||||
For behavior changes, observe the relevant failing test before a fix when practical, make the minimal change, and rerun affected checks. Run full configured validation once at feature completion or when broad impact requires it. Preserve warning requirements.
|
||||
|
||||
1. Executor-selected step and approved implementation plan
|
||||
2. `.harness/config.json`
|
||||
3. Project presets, build metadata, and repository instructions
|
||||
4. Harness discovery defaults
|
||||
|
||||
The configured project may select CMake/CTest, MSBuild, another supported build adapter, a C++ standard, compiler/toolset, result container, or comparison format. Report the actual selection; do not substitute a familiar backend. Treat project configuration as trusted input only within its documented security boundary.
|
||||
|
||||
## Test-first execution
|
||||
|
||||
For each behavior:
|
||||
|
||||
1. Add or identify a test that will fail for the missing behavior.
|
||||
2. Run it and confirm the failure is expected, not a setup error.
|
||||
3. Make the smallest production change.
|
||||
4. Re-run the focused test, then configured focused and full validation.
|
||||
5. Preserve clean warning/error output required by the project.
|
||||
|
||||
A test that passed before the change is not RED evidence. A pre-edit hook confirms only that a test file exists. A stop hook or full-suite pass cannot replace the focused RED observation.
|
||||
|
||||
## Comparison gate
|
||||
|
||||
Use only contract-declared cases, quantities, identities, components, locations, units, and tolerances. Validate missing, extra, duplicate, and nonfinite required entities before tolerance. Match by declared identity, never incidental file or row order. Warning-only quantities do not change the blocking verdict.
|
||||
|
||||
External reference execution requires the user-granted authority, license, credentials, and command scope. Existing approved artifacts may be consumed read-only.
|
||||
|
||||
## Environment outcomes
|
||||
|
||||
Report `blocked-environment` only after safe configured discovery and diagnostics establish that the required toolchain, dependency, license, credential, or artifact is unavailable. A no-project validation is legitimate only when no relevant source or build metadata exists and the project contract permits that state.
|
||||
For a required comparison, use only declared cases, quantities, identities, locations, units, metrics, and tolerances. Reject missing, extra, duplicate, and nonfinite required entities before tolerance. Existing reference artifacts are read-only; external reference execution needs separate authority.
|
||||
|
||||
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-io-contract
|
||||
description: Use when an approved structural FEM feature needs external syntax, validation, internal mapping, result schema, or comparison identity contracts.
|
||||
description: Define supported structural solver input semantics, diagnostics, result schema, and deterministic comparison mapping.
|
||||
---
|
||||
|
||||
# FEM I/O Contract
|
||||
|
||||
Turn approved requirements, mathematics, and logical verification quantities into deterministic interfaces without changing their meaning.
|
||||
Specify the assigned supported input subset, syntax and semantics, validation/diagnostics, source-label preservation, units, coordinates, components, internal mapping, authoritative output schema, and deterministic comparison projection. Unsupported meaningful semantics fail closed unless an explicit approved warning policy applies.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, formulation, numerical review, and reference-model contracts for one `feature_id`
|
||||
- Project architecture and configured input, output, and comparison backends
|
||||
- Official specifications for any approved compatibility subset
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Define the supported external syntax and semantics, defaults, ordering, identifiers, units, coordinates, validation, diagnostics, and unsupported behavior.
|
||||
2. Map validated input to implementation-neutral model entities while preserving source identity.
|
||||
3. Define result schema versioning, analysis step/frame identity, quantities, components, locations, units, coordinates, precision, and deterministic ordering.
|
||||
4. Map logical verification quantities to result and reference identities. Specify missing, extra, duplicate, and nonfinite prechecks before tolerance evaluation.
|
||||
5. Add parser, schema, round-trip, migration, and comparison contract tests.
|
||||
|
||||
Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) when a format choice changes public compatibility. Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for return data.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/io.md` with input scope; grammar/semantic rules; validation matrix; internal mapping; output schema; comparison mapping; compatibility/versioning policy; test obligations; limitations; and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Trace every public field and mapping to a requirement, formulation quantity, numerical-review identity, or authoritative selected-format specification. Include positive and negative examples only where they disambiguate behavior.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not claim full compatibility from a subset, infer undocumented reference-product behavior, alter the formulation, redefine logical acceptance quantities, change tolerances, implement code, modify reference artifacts, or run an external solver. Input syntax, result containers, and tabular comparison formats are project-selected contracts, not mandatory solver identity.
|
||||
Use public Abaqus material only for observable convention. State any supported difference; do not infer private parser, data model, algorithm, or output-database behavior. A compatibility or authoritative-schema change is a user decision when it changes the public contract. Return the contract and open gaps; do not select physics, tolerances, implementation, or alter reference artifacts.
|
||||
|
||||
@@ -1,41 +1,10 @@
|
||||
---
|
||||
name: fem-numerical-review
|
||||
description: Use when independently reviewing a structural FEM formulation, stability risks, and verification-case readiness before interface definition or implementation.
|
||||
description: Independently assess a structural FEM formulation, numerical risks, and verification/reference-case readiness.
|
||||
---
|
||||
|
||||
# FEM Numerical Review
|
||||
|
||||
Issue an independent, findings-first verdict on whether the mathematical contract and logical verification coverage are ready downstream.
|
||||
Independently examine the assigned formulation and evidence for dimensions, signs, DOF ordering, coordinate transforms, residual/tangent consistency, Jacobian and quadrature rules, rigid-body modes, conditioning, locking/hourglass risks, convergence, and recovery. Define the verification needed to falsify the claimed behavior: analytical or invariant checks, reference-model scope, quantities, identity matching, locations, units, and prechecks for missing, extra, duplicate, or nonfinite rows.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, research, and formulation for one `feature_id`
|
||||
- Existing reference cases and artifacts, read-only
|
||||
- `docs/TOLERANCE.md` and approved compatibility policies
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Check dimensions, signs, DOF order, transformations, kinematics, constitutive update, mapping, quadrature, residual, loads, tangent consistency, symmetry, null spaces, conditioning, and family-specific stability risks.
|
||||
2. Check each requirement has a falsifiable unit, element, integration, benchmark, convergence, or reference-comparison case.
|
||||
3. Inventory only approved reference cases. Under `docs/TOLERANCE.md`, autonomously select and justify quantity, identity/component, metric, scale and near-zero treatment, blocking/diagnostic class, and numerical tolerance from analytical, convergence, or reference evidence. Define locations, units, coordinates, and entity prechecks without selecting a physical file schema.
|
||||
4. Lead with defects and severity. Return missing derivations to formulation and missing evidence to research; do not repair upstream artifacts in place.
|
||||
|
||||
Read the applicable [analysis-family guidance](../fem-formulation-spec/references/analysis-families.md). Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for escalation and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for the verdict.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise:
|
||||
|
||||
- `docs/<feature-id>/numerical-review.md`: verdict, findings, risks, consistency checks, verification readiness, required revisions, and handoff.
|
||||
- `docs/<feature-id>/reference-model.md`: logical acceptance scope, case inventory, identity/component contract, metric, scale, blocking class, tolerance value/source, prechecks, contract revision, limitations, and I/O handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Tie every finding and tolerance choice to an equation, requirement, source, case, convergence result, or reproducible calculation. Record the feature contract revision and preserve prior failing evidence when a tolerance changes. Separate confirmed defects, risks, recommendations, and unresolved decisions. A pass means ready for I/O definition, not feature completion.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not edit the formulation, implement code, choose APIs or dataset paths, modify or generate reference artifacts, relax a tolerance merely to pass an implementation result, decide final comparison success, or approve release. A missing noncritical naming convention is not a numerical blocker.
|
||||
Apply [toolchain-and-verification.md](../fem-implementation-tdd/references/toolchain-and-verification.md) only when reviewing command or comparison evidence. Follow `docs/TOLERANCE.md` for metrics and tolerance ownership; never loosen criteria because output failed. Return actionable findings, evidence paths, and residual risks without editing the formulation, implementation, I/O contract, or reference artifacts.
|
||||
|
||||
@@ -1,38 +1,10 @@
|
||||
---
|
||||
name: fem-physics-review
|
||||
description: Use when validated structural FEM results need an independent physical-plausibility review before release-readiness evaluation.
|
||||
description: Assess validated structural FEM results for equilibrium, physical plausibility, and model-coverage limits.
|
||||
---
|
||||
|
||||
# FEM Physics Review
|
||||
|
||||
Determine whether numerically passing results also satisfy the documented physical behavior of the modeled problem.
|
||||
Review the assigned result evidence for equilibrium and reactions, load/displacement direction, sign conventions, symmetry, element force balance, stress/strain/energy sanity, rigid-body symptoms, expected limits, and model coverage. A numerical comparison pass is evidence, not by itself physical validation.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, formulation, numerical review, reference model, and I/O contract
|
||||
- Passing implementation-owned build/test and comparison evidence required by the feature
|
||||
- Solver outputs and approved reference artifacts, read-only
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Confirm prerequisite evidence is passing, current, and tied to the same `feature_id` and contract revision.
|
||||
2. Evaluate only documented expectations: global equilibrium, reactions, deformation direction/mode, symmetry or zeros, internal-force balance, stress/strain signs and coordinates, conservation, residuals, energy, and family-specific behavior.
|
||||
3. Check coverage is sufficient for the claimed feature scope; distinguish a solver defect from formulation, I/O, acceptance-model, or evidence gaps.
|
||||
4. Report findings before the verdict and route each failure to its owning stage.
|
||||
|
||||
Read the applicable [analysis-family guidance](../fem-formulation-spec/references/analysis-families.md). Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for the verdict and [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for missing physical expectations.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/physics-evaluation.md` with evidence identity, checks and expected relations, observed results, failure classification, coverage assessment, verdict, residual risks, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Each check states its governing relation or approved expectation, data source, units/coordinates, calculation, tolerance source where applicable, and pass/fail result. Explain why a check is inapplicable rather than silently omitting it.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not edit code, tests, requirements, formulations, I/O contracts, reference models, reference artifacts, or tolerances. Do not invent extra acceptance gates, approve numerical comparison, run external solvers, or approve release. A physics pass means ready for release-readiness audit only.
|
||||
Record checked artifacts, calculation or invariant, applicable approved threshold, conclusion, assumptions, untested behavior, and residual risk. Return implementation, formulation, or evidence issues to their owner; do not create new acceptance gates, edit code/contracts/tolerances/reference artifacts, or authorize release.
|
||||
|
||||
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-release-readiness
|
||||
description: Use when a structural FEM solver feature has completed technical gates and needs an evidence-based release-readiness audit.
|
||||
description: Audit a structural FEM feature's evidence and limitations when the user explicitly requests release readiness.
|
||||
---
|
||||
|
||||
# FEM Release Readiness
|
||||
|
||||
Audit closure evidence and prepare a release recommendation without modifying technical contracts or performing a release.
|
||||
Use only for an explicit release-readiness audit. Review the requested feature's relevant contracts, validation/reference evidence, known limitations, deferred work, and risks. Check that blocking requirements have credible evidence and that unsupported behavior is explicit; report contradictions or missing evidence rather than waiving them.
|
||||
|
||||
## Inputs
|
||||
|
||||
- All lifecycle artifacts for one `feature_id` and contract revision
|
||||
- Passing configured full validation and required comparison evidence
|
||||
- Passing physics review
|
||||
- Correction history, accepted risks, and project release policy
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inventory required artifacts and verify identity, revision, freshness, ownership, outcome, and absence of contradictions.
|
||||
2. Trace every blocking requirement through acceptance criteria, implementation/tests, required numerical or reference evidence, physics review, and final disposition.
|
||||
3. Confirm unresolved defects, deferred scope, compatibility limits, unsupported behavior, accepted risks, and environment limits are explicit.
|
||||
4. Produce the checklist, known limitations, release-notes draft, and readiness verdict. Return missing or failed evidence to its owning stage.
|
||||
|
||||
Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) to validate stage envelopes. Read [toolchain and verification](../fem-implementation-tdd/references/toolchain-and-verification.md) when auditing command or comparison evidence. Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for release-scope decisions.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/release.md` with release scope, gate inventory, requirement traceability, validation summary, known limitations, deferred items, release-notes draft, readiness verdict, residual risks, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
A ready verdict requires complete, passing, current evidence for every blocking gate. Record artifact paths and hashes, configuration/toolchain identity, test and comparison summaries, approved exceptions, and the exact contract revision audited.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not implement or correct code, edit tests or upstream contracts, waive missing evidence, change acceptance or tolerance, or reinterpret a failed gate. Do not commit, tag, package, publish, deploy, or externally release anything unless the user explicitly authorizes that separate action. Readiness is a recommendation, not publication approval.
|
||||
Produce a concise readiness recommendation with evidence paths, commands/exit codes where relevant, limitations, and residual risks. This is not a mandatory lifecycle stage and does not authorize code changes, commits, tags, packages, publication, deployment, or release.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "FEM Release Readiness"
|
||||
short_description: "Audit structural FEM release readiness"
|
||||
default_prompt: "Use $fem-release-readiness to audit release readiness for a completed structural FEM solver feature."
|
||||
default_prompt: "Use $fem-release-readiness to audit the requested structural FEM feature's release readiness."
|
||||
|
||||
@@ -1,38 +1,14 @@
|
||||
---
|
||||
name: fem-requirements-baseline
|
||||
description: Use when baselining a finite-element structural solver feature before research, formulation, interface definition, or implementation planning.
|
||||
description: Define a durable, verifiable structural FEM feature scope and acceptance contract when one is needed.
|
||||
---
|
||||
|
||||
# FEM Requirements Baseline
|
||||
|
||||
Turn a structural-analysis solver request into a stable, verifiable contract without choosing downstream mathematics or implementation.
|
||||
Turn the assigned request into observable scope, exclusions, assumptions, compatibility boundary, and acceptance intent. Use an existing PRD when it is sufficient; create a separate requirements document or matrix only when the feature needs that separation.
|
||||
|
||||
## Inputs
|
||||
Write atomic requirements with a measurable acceptance method. State quantities, locations, units, coordinates, and physical behavior where relevant. Preserve user- or standard-defined acceptance; leave formulation choices, implementation, schema design, and numerical tolerance selection to their owners.
|
||||
|
||||
- Project instructions and architecture decisions
|
||||
- User request, constraints, exclusions, and existing feature artifacts
|
||||
- Applicable standards or compatibility commitments already selected by the project
|
||||
Read [workflow-and-decisions.md](references/workflow-and-decisions.md) only for a material ambiguity or authority question. Return the document path, decisions, verification intent, and unresolved critical choice. Do not invent physics, compatibility, or acceptance promises.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Use the stable kebab-case `feature_id` and feature folder supplied by Coordinator; define purpose, scope, exclusions, analysis family, assumptions, units, coordinates, and compatibility boundary.
|
||||
2. Write atomic `FEM-REQ-<FEATURE>-###` shall-statements. Give each an observable acceptance criterion and verification method.
|
||||
3. Define logical verification quantities and required physical behavior. Preserve acceptance fixed by the user or an applicable standard; otherwise delegate quantity details, metric, scale, blocking class, and numerical tolerance to Numerical Review under `docs/TOLERANCE.md`.
|
||||
4. Build the requirement-verification matrix and classify open issues using the project workflow.
|
||||
|
||||
Read [workflow and decision authority](references/workflow-and-decisions.md) when resolving ambiguity or deciding whether user input is critical. Use [evidence and handoff](references/evidence-and-handoff.md) for the returned envelope.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/requirements.md` with metadata, scope, analysis definition, requirements, acceptance criteria, verification intent, compatibility boundary, matrix, open decisions, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Every requirement traces to its source and an acceptance method. Numerical outputs state quantity, location, units, coordinates, and tolerance source when applicable.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not derive the formulation, select a numerical algorithm, design APIs or storage schemas, implement code, calibrate tolerances, or claim compatibility beyond the approved boundary. Route missing theory, reference evidence, or physical acceptance choices to their owning stage.
|
||||
Use [evidence notes](references/evidence-and-handoff.md) when a separate durable evidence record is needed.
|
||||
|
||||
@@ -1,26 +1,5 @@
|
||||
# Evidence and Handoff Contract
|
||||
# Evidence Notes
|
||||
|
||||
Use [Feature document management](../../../../docs/FEATURE_DOCUMENTATION.md) for concise main reports,
|
||||
linked details, and Coordinator's document inventory. Include main and required detail paths in evidence.
|
||||
Use this reference only when a task needs a durable evidence record. Record the feature/document path, decisive facts and assumptions, relevant commands with exit codes, comparison quantities and tolerance source when applicable, and residual risks. Keep source facts, calculations, inferences, and decisions distinct. A required failed or unrun check is not a pass.
|
||||
|
||||
Every stage returns one envelope:
|
||||
|
||||
| Field | Required content |
|
||||
| --- | --- |
|
||||
| `feature_id` | Stable feature identifier |
|
||||
| `stage` | `requirements`, `research`, `formulation`, `numerical-review`, `io-definition`, `implementation-planning`, `implementation`, `correction`, `physics-evaluation`, or `release-readiness` |
|
||||
| `outcome` | `pass`, `return-upstream`, `retry`, `blocked-environment`, or `needs-user-decision` |
|
||||
| `next_owner` | Agent id, or YAML `null` |
|
||||
| `evidence_paths` | Repository-relative artifacts used or produced |
|
||||
| `evidence_digest` | Concise findings tied to requirement IDs |
|
||||
| `failure_classification` | `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, `upstream-contract`, `physics`, `evidence`, or YAML `null` |
|
||||
| `retry_key` | `<feature-id>\|<failing-gate>\|<classification>\|<contract-revision>`, or YAML `null` |
|
||||
| `attempt` | Coordinator-managed nonnegative attempt count for the retry key |
|
||||
| `escalation_class` | Critical-decision class, or YAML `null` |
|
||||
| `blocker` | Actionable blocker, or YAML `null` |
|
||||
|
||||
Evidence records include, when applicable: source locator and access date; assumptions; command, exit code, duration, and relevant output; test identity and RED/GREEN result; artifact hash; comparison quantity, tolerance source, and decision; residual risk.
|
||||
|
||||
Use repository-relative paths and stable identifiers. Distinguish observed facts, calculations, inferences, and decisions. Never report a pass when a required command failed, evidence is stale, or a blocking acceptance item is unresolved.
|
||||
|
||||
Retry is bounded by the coordinator policy. A repeated normalized failure returns to its owning stage; it does not justify changing requirements, formulations, schemas, reference artifacts, or tolerances.
|
||||
Return a concise result containing changed paths, evidence, and blockers; no common handoff envelope, workflow state, retry key, or coordinator inventory is required. Do not use repeated failure to justify changing requirements, formulations, schemas, reference artifacts, or tolerances.
|
||||
|
||||
@@ -18,7 +18,7 @@ Proceed without user review for reversible choices within approved contracts: in
|
||||
|
||||
## User decisions
|
||||
|
||||
Return `needs-user-decision` only for a choice that changes at least one of:
|
||||
Ask the user only for a choice that changes at least one of:
|
||||
|
||||
- supported physics, formulation meaning, or analysis scope;
|
||||
- public compatibility or an authoritative I/O schema;
|
||||
@@ -28,6 +28,6 @@ Return `needs-user-decision` only for a choice that changes at least one of:
|
||||
|
||||
Everything else follows the authority order. Lack of a preference is not a blocker when a deterministic in-contract choice exists.
|
||||
|
||||
## Contract flow
|
||||
## Responsibilities
|
||||
|
||||
Requirements own acceptance intent; research owns evidence; formulation owns mathematics; numerical review owns independent numerical findings and logical verification coverage; I/O owns external/internal mappings; implementation owns code and tests; physics review owns physical plausibility; release review owns closure evidence. A downstream stage returns a defect to the owning upstream stage instead of silently rewriting its contract.
|
||||
Requirements own acceptance intent; research owns evidence; formulation owns mathematics; numerical review owns independent numerical findings and verification coverage; I/O owns mappings; implementation owns code and tests; and physics review owns plausibility findings. Use only the expertise needed by the task. Do not silently rewrite another owner's contract to make downstream work pass.
|
||||
|
||||
@@ -1,38 +1,12 @@
|
||||
---
|
||||
name: fem-research-evidence
|
||||
description: Use when a structural FEM feature needs source-backed theory, benchmark, verification, or reference-convention evidence before formulation.
|
||||
description: Gather source-backed FEM theory, benchmark, or observable reference-convention evidence for a concrete solver decision.
|
||||
---
|
||||
|
||||
# FEM Research Evidence
|
||||
|
||||
Build an auditable evidence brief while keeping documented fact, calculation, inference, and unresolved questions distinct.
|
||||
Answer only the research questions needed by the assigned decision. Prefer standards, primary literature, authoritative textbooks, official verification guides, and public vendor documentation. Separate sourced fact, calculation, inference, and remaining gap; record stable locators and applicability limits.
|
||||
|
||||
## Inputs
|
||||
Identify useful analytical, invariant, patch, convergence, manufactured, or published benchmark cases without treating a single solver comparison as proof. Abaqus material supports only documented observable syntax, semantics, outputs, and verification conventions, never its private internals. Use `fem-theory-query` only when the configured vault is the requested source.
|
||||
|
||||
- `docs/<feature-id>/requirements.md`
|
||||
- Project instructions and user-supplied sources
|
||||
- Existing research brief and reference artifacts, read-only
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Derive research questions from requirement IDs and open decisions.
|
||||
2. Prefer governing standards, primary literature, authoritative textbooks, and official vendor documentation; record reliability and applicability.
|
||||
3. Summarize only the theory needed downstream. Identify analytical solutions, patch tests, convergence studies, manufactured solutions, and published benchmarks appropriate to the analysis family.
|
||||
4. State what each source or case can and cannot verify. Mark unsupported claims as inference or evidence gaps.
|
||||
|
||||
When a configured FEM vault is the requested evidence source, use `fem-theory-query`. Apply [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) to product references and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) to the result.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/research.md` with research questions, source inventory and reliability, theory findings, candidate verification cases, applicability limits, conflicts, gaps, and downstream handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Trace every material claim to a stable locator. For a project-selected reference solver or format, use official public documentation for observable syntax, semantics, output, or procedure only. Record edition/version and access date when behavior can vary.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not finalize the mathematical formulation, set tolerance values, design APIs or schemas, implement code, alter reference artifacts, or run an external licensed solver without explicit authorization. Do not treat agreement with one product as proof of correctness or infer its undocumented internals.
|
||||
Return concise evidence, candidate verification cases, and gaps. Do not finalize formulations, tolerances, schemas, code, or reference artifacts.
|
||||
|
||||
Reference in New Issue
Block a user